Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Changelog

Every version of this document, newest first, with the day it reached production. Additive changes — new fields, new operations, new optional parameters — ship without a path-version change and bump info.version; see Versioning and deprecation for what each kind of change means for a caller.

2.3.2 — released 2026-09-29

  • The MCP hints (x-mcp-annotations) now say what each operation does, and no operation is published as read-only. Every operation that reserves credits — the eight job submits, the eight batch submits and the synchronous routes — is readOnlyHint: false and idempotentHint: false: an accepted call debits credits, creates a job or call record and is kept in the team's resolution history, and a repeat is a new charge. POST /v1/name and its batch and GET /v1/company are openWorldHint: false: they compute from the request and Delpha's own data and reach no external system. The result reads — single and batch — are readOnlyHint: false with idempotentHint: true: a read adds no charge and a repeat returns the same answer, but the read that observes a finished job settles its charge (or refunds it when the job failed or produced no usable result), and a read past the job's time limit marks the job failed. Each result read now states this in its description and in x-side-effects.

  • New x-mcp-omit extension on POST /v1/website, POST /v1/linkedin-profile, POST /v1/linkedin-company-page (email) and POST /v1/phone (country): fields the MCP server withholds from its tool input because another field carries the same signal. The REST contract is unchanged and still accepts them.

  • Every job submit now opens with the input it needs, and the descriptions say what leaves Delpha for a website search (a web-search provider and Delpha's AI provider) and for a legal-ID lookup (the selected country's public registry; a company found there is added to Delpha's datalake). legal_id and the legal-ID address are described as the company's registry number and registered address, never a person's. An email sent to the LinkedIn tools is used only for its domain, and the descriptions now say so.

  • The Data sources and privacy table now covers every operation, the company ones included: what POST /v1/website, POST /v1/legal-id and POST /v1/ultimate send outside Delpha and to whom, and that a legal-ID registry result is kept in Delpha's company datalake. POST /v1/ultimate states its recipients in its own description too.

  • POST /v1/linkedin-company-page/batch items no longer list first_name and last_name, which the lookup never used; they are still accepted. The company-page batch result example now shows a company page instead of a person's profile.

  • A GET /v1/linkedin-profile/{job_id} result now reports an outdated profile URL: url_changed is true when the URL you submitted was not found while exactly one other profile matching the person was, and suggested_url names that profile. LinkedIn does not redirect a profile whose address was changed, so the old address simply stops working. scores.validity still checks the URL's format only, and the URL you submit is no longer requested at all.

2.3.1 — released 2026-09-24

  • GET /v1/linkedin-company-page/{job_id} now has its own result schema. Its candidates no longer list job_title or profile_name, and the result no longer lists fallback_used: on a company page the first was always null, the second was null or repeated the page name, and the third was always false, because the name-only fallback searches for a person. Read the page name from headline or company_name. GET /v1/linkedin-profile/{job_id} is unchanged.

2.3.0 — released 2026-09-23

  • A new Data sources and privacy guide. For every operation that can return information about a person it states what the request supplies, where the result comes from, and which values leave Delpha and to what kind of provider; the providers themselves are named individually in Delpha's sub-processor list. It also publishes what each store keeps and for how long, including the resolution-history window your team sets and the retention that applies when it is set to 0.

  • Every operation that spends credits now states its own side effects in its description: what a call reserves, what is recorded and for how long, what a repeat submission costs, and what a test-mode call does instead.

  • The operations that can return information about a person each carry one sentence naming where their result comes from, and what — if anything — is sent outside Delpha to produce it.

  • The guide also states Delpha's role for each call (processor for the customer under the GDPR, service provider under the CCPA, controller of its cross-customer verification cache) and gives anyone whose data was checked a direct contact for access, correction and erasure requests.

  • Every operation that starts a job now publishes idempotentHint: false in x-mcp-annotations: without an Idempotency-Key, repeating a submit starts a new job and a new charge. Each operation's side-effect note is also published on its own, as x-side-effects.

  • The ultimate-parent operations describe the parent they return as the commercial parent — the operating group a company is sold to and routed under — with passive holding entities flagged is_discarded and a financial owner returned separately. The getUltimateParentResult field list names source_url, the field the result actually carries.

  • Descriptions throughout are now statements of what an operation does and returns rather than instructions to the caller, and the tag summaries describe the operations instead of the product.

  • Three corrections. email_domain_qualification is documented as the five values the API returns, each defined as a property of the address's domain. The ultimate-parent documentation states that GLEIF metadata is carried when a match is found and is null when none is. The name operation no longer claims to return signals it has never computed; its description now lists what it does return, and states that characters outside the Latin script are removed during normalization.

2.2.0 — released 2026-09-23

  • LinkedIn profile and company-page requests now have separate schemas, including batch items, with operation-specific parameter descriptions and URL examples. The single company-page schema no longer advertises first_name or last_name; existing callers can still send them.

  • Corrected the email label documentation to list No, OK, and OddFormat. Website documentation now explains when a redirect destination is adopted — same registrable domain, or the evidence ranking it above the original, or a corroborating search candidate — its host-only normalization, and the Changed and Unknown verdicts: Changed reports an adopted move, and Unknown means the request named no company, so accuracy had no basis.

  • The LinkedIn result label now reads OK, the casing every other use case already publishes, instead of Ok. Update any comparison against "Ok". The API accepts both spellings from the verification backend and will keep doing so, so nothing is lost in transit; only the value the API publishes changes. Batch results are normalized the same way, in both the inline payload and the downloadable file.

2.1.0 — released 2026-09-23

  • Every legal-ID suggestion and match (GET /v1/legal-id/{job_id}) now carries site_type — headquarters, branch, or unknown when the register holds no value; an open vocabulary, so treat it as a string — and vat, the entity's VAT identifier when one is known. They are the fields GET /v1/company already publishes for the same record (spelled site_type and VAT there).

  • This was more than a documentation gap: the verification backend was already returning both, and GET /v1/legal-id/batch/{job_id} already carried them, while the single poller discarded them before the response was written.

2.0.0 — released 2026-09-16

  • Withdrawn: the address operations (POST /v1/address, its poller and its batch pair). The postal-address verification is no longer offered on the public API.

  • Withdrawn: the LinkedIn import operations (POST /v1/linkedin-import and its poller) and the LinkedIn scraper operations (POST /v1/linkedin-scraper and its poller).

  • Withdrawn: the combined LinkedIn operations (POST /v1/linkedin, its poller and its batch pair), deprecated since 1.2.0 in favour of /v1/linkedin-profile and /v1/linkedin-company-page, which are unchanged and take the same body.

  • Withdrawn: POST /v1/email-insights.

  • Results now name fields the verification backends were already returning and this document did not describe: email_address_qualification on an email result (Spam Trap / Role-based, which takes precedence over the domain qualification), confidence in a phone result's scores, activity_score and is_prepaid on both phone operations, type on a LinkedIn result, and headquarters_site on every legal-ID suggestion and match.

  • One of those was more than a documentation gap: a phone result's scores.confidence was being discarded before the response was written, so POST /v1/phone and GET /v1/phone/{job_id} never carried it while POST /v1/phone/batch did. Both now return it.

1.5.0 — released 2026-09-15

  • Test mode: an API key can now be created in test mode, and calls made with one are answered from a published table of canned results — no credits reserved or settled, no verification backend or data provider queried, and the same operations, schemas, validation, idempotency and polling contract as a live key. The mode is chosen when the key is created and cannot be edited afterwards.

  • Every response the API renders to a test-mode call carries X-Delpha-Mode: sandbox; a live response carries no such header. The 401, 403 and shared-floor 429 the gateway answers itself carry none of the per-request headers.

  • A test-mode job is complete when it is accepted, so its first poll answers 200 rather than the transient 202 — the submit, its Location and Retry-After and its idempotency behaviour are unchanged.

  • Webhook events for a test-mode job carry data.mode, and the WebhookEvent schema now declares it. Test-mode and live jobs are isolated: polling one with the other mode's key answers 404.

  • POST /v1/email-insights is served by a different service and has no test-mode implementation, so a test-mode key is refused there instead of being served a live, billable answer.

1.4.0 — released 2026-09-15

  • Every response the API renders now reports what is left of your allowance: X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, plus the RateLimit and RateLimit-Policy structured fields. The gateway's own 401 and 403 are answered before the API sees the request and carry none of them.

  • Rate limits are counted per credential owner and per operation — per team for an API key, per OAuth client for the client-credentials flow — in fixed 60-second windows, so one caller's burst no longer consumes another's headroom below the shared floor.

  • A 429 now takes one of two documented shapes: your own allowance answers with the standard error envelope (code: rate_limited), the quota headers and a Retry-After of the seconds left in the window; the per-operation floor shared by all callers answers earlier, with Retry-After: 1.

  • Each operation's x-rate-limit extension now publishes the policy that governs it, its quota and window, and the headers it returns.

1.3.1 — released 2026-09-14

  • Every value of the error code enum now carries its own published meaning, the status it usually rides on and what to do about it — in the document, on the error reference page, and on every endpoint page that references the error envelope.

  • The OAuth api/access scope is documented as all-access: per-use-case scoping, per-key credit ceilings and expiry are properties of an API key.

  • Batch settlement is documented as partial — only the items that succeed are charged.

  • Each published document now describes only the environment it is published for: the production document lists the production server alone, and every example names production. A client generated from it offers one base URL instead of two.

  • These guide and reference pages are generated from the document itself, so they change in the release that changes the API.

1.3.0 — released 2026-09-10

  • Cursor pagination on GET /v1/company: the cursor query parameter, next_cursor on the result, a nullable page on a cursor page, and the 422 that says a cursor was refused.

1.2.0 — released 2026-09-10

  • The agent integration guide in the document's own description — the source these pages are generated from.

  • Signed webhook lifecycle events (sent, done, error) published as a webhooks section, with the event schema.

  • Deprecation and Link response headers on every response of a deprecated operation.

1.1.0 — released 2026-09-10

  • A typed error envelope: a stable machine-readable code, a request_id for support correlation, and a doc_url once the error reference is published.

  • The gateway's 401, 403 and 429 documented on every operation.

  • Per-operation idempotency and rate-limit extensions (x-idempotency, x-rate-limit), plus typical latency, submit/poll pairing and credit operation.

1.0.0 — released 2025-07-21

  • First published OpenAPI document for the public API.

PreviousVersioning and deprecation
NextEmail

Last updated

Was this helpful?