> For the complete documentation index, see [llms.txt](https://help.delpha.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.delpha.io/delpha-api-and-mcp/api/legal-id.md).

# Legal ID

Legal identifiers are the foundation of corporate trust and compliance—yet they often vary in format and structure from one country to another. Delpha's **Legal ID Finder** and **Legal ID Validator** simplify the verification and normalization of company registration numbers worldwide, ensuring your records remain consistent, authentic, and enriched with reliable context.

Each request is assessed through several key dimensions:

* **Completeness:** Detects missing or incomplete identifiers and, when possible, infers the ID type from the provided country.
* **Validity:** Confirms that the ID follows the official structure and exists within Delpha's trusted registry for supported countries (see documentation for full coverage).
* **Consistency:** Compares your input with its normalized version, applying the appropriate format, padding, and length rules.
* **Accuracy:** Verifies whether the provided ID matches contextual data such as company name or address.

When valid, Delpha returns a **normalized and enriched record** containing structured details like company name, address, website, and industry. If side fields are provided, the **Legal ID Finder** can also deliver **AI-generated recommendations** with confidence scores to help identify the correct registered entity.

With **Legal ID Finder** and **Legal ID Validator**, you gain a consolidated, cross-country view of legal identifiers—enhancing data quality, reliability, and compliance at scale.

## Find & validate legal ID

> Submit an asynchronous job to find and validate a company's legal identifier (SIRET, SIREN, NZBN, ABN, CIK, ...). Returns a \`job\_id\` — pass it to \`getLegalIDResult\` to retrieve the normalized identifier, the resolved \`legal\_id\_type\`, and validity / accuracy scores.\
> \
> \*\*Required:\*\* the job must know which registry to target, so you MUST provide at least one of:\
>   \- \`legal\_id\_type\` — the registry directly (e.g. \`FRA - SIRET\`, \`GBR - COMPANY REGISTRATION NUMBER\`), or\
>   \- \`address.country\` — the entity's country, from which the registry is inferred.\
> \
> A call that provides neither is rejected with 400 (\`Either 'legal\_id\_type' or 'address.country' must be provided\`) — e.g. \`{name, website}\` alone fails. Beyond that requirement, supply whatever you have to improve the match: \`legal\_id\` (validation mode), \`name\`, and/or \`website\` (search mode).\
> \
> \*\*Coverage:\*\* only the registries in the \`legal\_id\_type\` enum can be queried. A request naming any other registry, or a country that has no registry in that list, is refused with \*\*422 \`unsupported\_registry\`\*\* \*before any credit is reserved\*; the message lists the supported countries. Do not retry such a request with the same country — fixing \`name\` or \`legal\_id\` will not help. An explicit \`legal\_id\_type\` takes precedence over \`address.country\`, so a supported registry with an unsupported country still runs.

```json
{"openapi":"3.1.0","info":{"title":"Delpha Data Quality API","version":"2.0.0"},"tags":[{"name":"Legal ID","description":"Legal identifiers are the foundation of corporate trust and compliance—yet they often vary in format and structure from one country to another.\nDelpha's **Legal ID Finder** and **Legal ID Validator** simplify the verification and normalization of company registration numbers worldwide, ensuring your records remain consistent, authentic, and enriched with reliable context.\n\nEach request is assessed through several key dimensions:\n- **Completeness:** Detects missing or incomplete identifiers and, when possible, infers the ID type from the provided country.\n- **Validity:** Confirms that the ID follows the official structure and exists within Delpha's trusted registry for supported countries (see documentation for full coverage).\n- **Consistency:** Compares your input with its normalized version, applying the appropriate format, padding, and length rules.\n- **Accuracy:** Verifies whether the provided ID matches contextual data such as company name or address.\n\nWhen valid, Delpha returns a **normalized and enriched record** containing structured details like company name, address, website, and industry. If side fields are provided, the **Legal ID Finder** can also deliver **AI-generated recommendations** with confidence scores to help identify the correct registered entity.\n\nWith **Legal ID Finder** and **Legal ID Validator**, you gain a consolidated, cross-country view of legal identifiers—enhancing data quality, reliability, and compliance at scale."}],"servers":[{"url":"https://api.delpha.io","description":"Production API server"}],"security":[{"oauth2":["api/access"]},{"apiKey":[]}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth 2.0 client-credentials flow (machine-to-machine). Token URL: https://secure.delpha.io/oauth2/token. The `api/access` scope is all-access: it grants every operation this document publishes. Per-use-case scoping, per-key credit ceilings and expiry are properties of an API key, not of this flow — use an API key when a credential must be restricted.","flows":{"clientCredentials":{"tokenUrl":"https://secure.delpha.io/oauth2/token","scopes":{"api/access":"Access to the public API"}}}},"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"dlp_","description":"Native Delpha API key. Send it as an HTTP bearer token (`Authorization: Bearer dlp_...`). Keys are issued from the Delpha app (Developer → API keys) and are billed per team against the team's credit balance."}},"schemas":{"LegalIDSubmitOutput":{"additionalProperties":true,"description":"Response after submitting a new legal ID quality job.","properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Stable machine-readable status/error code (see ErrorCode).","title":"Code"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The API Gateway request id, for support correlation.","title":"Request Id"},"doc_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Link to error documentation (present when published).","title":"Doc Url"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The job ID. Required if status <= 300.","title":"Job Id"},"message":{"description":"The message to return","title":"Message","type":"string"},"status":{"description":"The status of the process","enum":["SUCCESS","ERROR"],"title":"Status","type":"string"},"status_code":{"description":"The status code to return","title":"Status Code","type":"integer"}},"required":["message","status","status_code"],"title":"LegalIDSubmitOutput","type":"object"},"Error":{"type":"object","title":"Error","description":"Typed error envelope emitted by the API for handler-level 4xx/5xx responses. Extends the success envelope with a stable machine-readable `code` and a correlation `request_id`.","properties":{"status":{"type":"string","enum":["ERROR"],"description":"Always \"ERROR\" for an error response."},"status_code":{"type":"integer","description":"The HTTP status code of the response."},"message":{"type":"string","description":"Human-readable, PII-free error message."},"code":{"type":"string","enum":["validation_error","unauthorized","payment_required","not_found","conflict","rate_limited","backend_error","backend_timeout","service_unavailable","job_timeout","internal_error","unsupported_registry","idempotency_key_reuse","idempotency_in_progress","idempotency_key_invalid"],"description":"Stable machine-readable error code. `ok` and `job_running` are the success-side codes and never appear in an error body."},"request_id":{"type":"string","description":"API Gateway request id, for support correlation. The same value is returned in the `x-amzn-RequestId` response header on every response, including the 401/403/429 API Gateway generates itself."},"doc_url":{"type":"string","description":"Link to error documentation. Present when error documentation is published."}},"required":["status","status_code","message"],"additionalProperties":true},"GatewayError":{"type":"object","title":"GatewayError","description":"Error body returned by API Gateway itself, before a handler runs: 401 (no or invalid credential), 403 (the API key's scopes do not cover this operation, or the path is not routed here) and 429 (stage throttle; carries `Retry-After`). It has no `code` and no `request_id`; correlate it through the `x-amzn-RequestId` response header instead. A 401 a handler emits after the gateway admitted the request carries the full `Error` envelope.","properties":{"status":{"type":"string","enum":["ERROR"],"description":"Always \"ERROR\"."},"status_code":{"type":"integer","description":"The HTTP status code of the response (401, 403 or 429)."},"message":{"type":"string","description":"Human-readable error message."}},"required":["message"],"additionalProperties":true},"LegalIDSubmitInput":{"description":"Payload to submit a new legal ID quality job.","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Legal or trade name of the entity (e.g. `Delpha`).","title":"Name"},"legal_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Existing legal identifier to validate (e.g. SIRET `88052440000012`). Format is registry-specific; supply `legal_id_type` when the format is ambiguous.","title":"Legal Id"},"legal_id_type":{"anyOf":[{"$ref":"#/components/schemas/LegalIDType"},{"type":"null"}],"default":null,"description":"Registry the `legal_id` belongs to. Closed enum of the registries Delpha can query today (e.g. `FRA - SIRET`, `USA - CIK`); any other value is refused with 422 `unsupported_registry` before any credit is reserved. Required only when the same numeric format exists in multiple registries."},"address":{"anyOf":[{"$ref":"#/components/schemas/AddressInput"},{"type":"null"}],"description":"Postal address of the entity. Used to disambiguate registry lookups by country / region."},"website":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"default":null,"description":"Entity website — the domain is used as a country signal during registry resolution.","title":"Website"}},"title":"LegalIDSubmitInput","type":"object"},"LegalIDType":{"description":"The legal ID registries Delpha can currently query.\n\nA request naming a registry outside this list is refused before any credits are\nconsumed.","enum":["FRA - SIRET","FRA - SIREN","NZL - NZBN","AUS - ABN","NOR - ORGANISASJONSNUMMER","CHE - UID","GBR - COMPANY REGISTRATION NUMBER","BEL - ENTERPRISE NUMBER","DEU - HANDELSREGISTERNUMMER","EST - COMMERCIAL REGISTER CODE","IRL - CRO NUMBER","ESP - NIF","NLD - KVK-NUMMER","CAN - CORPORATION-NUMBER","FIN - Y-TUNNUS","SWE - ORGANISATIONSNUMMER","USA - CIK"],"title":"LegalIDType","type":"string"},"AddressInput":{"description":"Model representing an address.","properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The street","title":"Street"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The city","title":"City"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The state","title":"State"},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The zip code","title":"Postal Code"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The country","title":"Country"}},"title":"AddressInput","type":"object"}},"headers":{"RateLimitLimit":{"description":"Your request allowance for this operation in the current 60-second window. It is counted per credential owner AND per operation: spending it on one operation does not reduce what you may send to another.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Requests still available to you on this operation in the current window. `0` on the request that exhausts it and on the refusals that follow.","schema":{"type":"string"}},"RateLimitReset":{"description":"When the current window resets, as **UTC epoch seconds** — an absolute instant, not a number of seconds to wait. Use `Retry-After` for the delay.","schema":{"type":"string"}},"RateLimit":{"description":"What is left of the allowance, as a structured field of `draft-ietf-httpapi-ratelimit-headers` (an Internet-Draft, not a published standard): `\"<policy>\";r=<remaining>;t=<seconds to reset>`. Exactly one policy governs a request, so the list always carries one member.","schema":{"type":"string"}},"RateLimitPolicy":{"description":"The allowance that governed this request, as a structured field of `draft-ietf-httpapi-ratelimit-headers` (an Internet-Draft, not a published standard): `\"<policy>\";q=<quota>;w=<window seconds>`. `submit` governs submit and synchronous operations, `poll` the poll operations; the policy for each operation is also published in its `x-rate-limit`.","schema":{"type":"string"}},"DelphaMode":{"description":"Present on every response the API renders to a **test-mode** key, and on no other: absence means the call was live. A test-mode call is answered from the published fixture table, reserves no credits and reaches no verification backend. The 401, 403 and shared-floor 429 the gateway answers before the API sees the request carry no per-request headers, so they never carry this one. See the *Test mode* section of this document.","schema":{"type":"string","enum":["sandbox"]}}}},"paths":{"/v1/legal-id":{"post":{"tags":["Legal ID"],"summary":"Find & validate legal ID","description":"Submit an asynchronous job to find and validate a company's legal identifier (SIRET, SIREN, NZBN, ABN, CIK, ...). Returns a `job_id` — pass it to `getLegalIDResult` to retrieve the normalized identifier, the resolved `legal_id_type`, and validity / accuracy scores.\n\n**Required:** the job must know which registry to target, so you MUST provide at least one of:\n  - `legal_id_type` — the registry directly (e.g. `FRA - SIRET`, `GBR - COMPANY REGISTRATION NUMBER`), or\n  - `address.country` — the entity's country, from which the registry is inferred.\n\nA call that provides neither is rejected with 400 (`Either 'legal_id_type' or 'address.country' must be provided`) — e.g. `{name, website}` alone fails. Beyond that requirement, supply whatever you have to improve the match: `legal_id` (validation mode), `name`, and/or `website` (search mode).\n\n**Coverage:** only the registries in the `legal_id_type` enum can be queried. A request naming any other registry, or a country that has no registry in that list, is refused with **422 `unsupported_registry`** *before any credit is reserved*; the message lists the supported countries. Do not retry such a request with the same country — fixing `name` or `legal_id` will not help. An explicit `legal_id_type` takes precedence over `address.country`, so a supported registry with an unsupported country still runs.","operationId":"findAndValidateLegalID","responses":{"202":{"description":"Accepted / still running — poll the result route with the returned job_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalIDSubmitOutput"}}},"headers":{"Location":{"description":"Poll URL for this job (present when the response carries a job_id).","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before polling again.","schema":{"type":"integer"}},"Idempotent-Replayed":{"description":"Set to 'true' when this 202 replays a previously accepted request with the same Idempotency-Key (no new job, no additional charge).","schema":{"type":"string"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"400":{"description":"Validation error — the request body or query parameters were rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"401":{"description":"Authentication failed — invalid or missing OAuth 2.0 token or API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}},"headers":{}},"402":{"description":"Payment required — the team has insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"403":{"description":"Forbidden — the credential is valid but not allowed here: the API key's scopes do not cover this operation, or the operation is not routed in this environment (API Gateway then answers `Missing Authentication Token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}},"headers":{}},"409":{"description":"Conflict — the `Idempotency-Key` was already used with a different request body (`idempotency_key_reuse`: use a new key), or the original request with this key is still being processed (`idempotency_in_progress`: retry the same request shortly).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"422":{"description":"Unprocessable entity — the request is well-formed but cannot be processed: a documented size/shape bound was violated (`validation_error`), or a legal-ID request names a registry / country Delpha cannot query (`unsupported_registry` — refused before any credit is reserved; the message lists the supported countries).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"429":{"description":"Too many requests — one of two limits was exceeded. Your allowance for this operation in the current 60-second window: an `Error` body with `code: rate_limited`, `Retry-After` set to the seconds left in the window, and the quota headers with `X-RateLimit-Remaining: 0`; nothing is charged. Or the per-operation floor every caller of that operation shares: a `GatewayError` body with `Retry-After: 1` and no quota headers, refused before the API sees the request.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying: the time left in your current window on the allowance refusal, and `1` on the shared per-operation floor.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"RateLimit":{"$ref":"#/components/headers/RateLimit","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no per-request headers."}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"502":{"description":"Bad gateway — the upstream service returned an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalIDSubmitInput"}}}}}}}}
```

## Get legal ID validation result

> Fetch the result of a previously submitted \`findAndValidateLegalID\` job by \`job\_id\`. On success, the \`result\` payload contains the normalized legal identifier, the resolved \`legal\_id\_type\` (which registry it belongs to), the validity / accuracy scores, a \`match\` object with the enriched company record (account name, address, annual revenue, employee count, industry, formation date, company type, website) when a confident match is found, and a \`suggestions\` array of alternative company records each ranked by confidence.

```json
{"openapi":"3.1.0","info":{"title":"Delpha Data Quality API","version":"2.0.0"},"tags":[{"name":"Legal ID","description":"Legal identifiers are the foundation of corporate trust and compliance—yet they often vary in format and structure from one country to another.\nDelpha's **Legal ID Finder** and **Legal ID Validator** simplify the verification and normalization of company registration numbers worldwide, ensuring your records remain consistent, authentic, and enriched with reliable context.\n\nEach request is assessed through several key dimensions:\n- **Completeness:** Detects missing or incomplete identifiers and, when possible, infers the ID type from the provided country.\n- **Validity:** Confirms that the ID follows the official structure and exists within Delpha's trusted registry for supported countries (see documentation for full coverage).\n- **Consistency:** Compares your input with its normalized version, applying the appropriate format, padding, and length rules.\n- **Accuracy:** Verifies whether the provided ID matches contextual data such as company name or address.\n\nWhen valid, Delpha returns a **normalized and enriched record** containing structured details like company name, address, website, and industry. If side fields are provided, the **Legal ID Finder** can also deliver **AI-generated recommendations** with confidence scores to help identify the correct registered entity.\n\nWith **Legal ID Finder** and **Legal ID Validator**, you gain a consolidated, cross-country view of legal identifiers—enhancing data quality, reliability, and compliance at scale."}],"servers":[{"url":"https://api.delpha.io","description":"Production API server"}],"security":[{"oauth2":["api/access"]},{"apiKey":[]}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth 2.0 client-credentials flow (machine-to-machine). Token URL: https://secure.delpha.io/oauth2/token. The `api/access` scope is all-access: it grants every operation this document publishes. Per-use-case scoping, per-key credit ceilings and expiry are properties of an API key, not of this flow — use an API key when a credential must be restricted.","flows":{"clientCredentials":{"tokenUrl":"https://secure.delpha.io/oauth2/token","scopes":{"api/access":"Access to the public API"}}}},"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"dlp_","description":"Native Delpha API key. Send it as an HTTP bearer token (`Authorization: Bearer dlp_...`). Keys are issued from the Delpha app (Developer → API keys) and are billed per team against the team's credit balance."}},"schemas":{"LegalIDPullOutput":{"additionalProperties":true,"description":"Response after retrieving the status and result of an legal ID quality job.","properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Stable machine-readable status/error code (see ErrorCode).","title":"Code"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The API Gateway request id, for support correlation.","title":"Request Id"},"doc_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Link to error documentation (present when published).","title":"Doc Url"},"message":{"description":"A human-readable message describing the current state or outcome of the job.","title":"Message","type":"string"},"status":{"description":"The status of the process","enum":["SUCCESS","ERROR"],"title":"Status","type":"string"},"status_code":{"description":"The HTTP status code representing the job's current state.","title":"Status Code","type":"integer"},"result":{"anyOf":[{"$ref":"#/components/schemas/LegalIDModel"},{"type":"null"}],"default":null,"description":"The result of the legal ID quality job"},"process_time":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"The total time taken to process the job, in seconds.","title":"Process Time"}},"required":["message","status","status_code"],"title":"LegalIDPullOutput","type":"object"},"LegalIDModel":{"additionalProperties":true,"description":"Model representing the details of a legal ID field.","properties":{"data_type":{"$ref":"#/components/schemas/DataType","description":"The type of data for this field"},"normalized_value":{"description":"Normalized legal ID value.","title":"Normalized Value","type":"string"},"label":{"description":"Label for the legal ID.","enum":["No","OK","Unknown"],"title":"Label","type":"string"},"legal_id_type":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The type of legal ID. Free-form: it normally matches one of the types accepted on submission. Null when no registry could be determined.","title":"Legal Id Type"},"scores":{"$ref":"#/components/schemas/ScoresModel","description":"Scores for the field"},"match":{"anyOf":[{"$ref":"#/components/schemas/LegalIDSuggestion"},{"type":"null"}],"default":null,"description":"The match information"},"suggestions":{"description":"Suggestions for the legal ID.","items":{"$ref":"#/components/schemas/LegalIDSuggestion"},"title":"Suggestions","type":"array"}},"required":["data_type","normalized_value","label","legal_id_type","scores","suggestions"],"title":"LegalIDModel","type":"object"},"DataType":{"enum":["email","social_network","name","legal_id","phone","address","website"],"title":"DataType","type":"string"},"ScoresModel":{"description":"Model representing the scores for an email field.","properties":{"accuracy":{"default":-1,"description":"Accuracy score","maximum":1,"minimum":-1,"title":"Accuracy","type":"number"},"validity":{"default":-1,"description":"Validity score","maximum":1,"minimum":-1,"title":"Validity","type":"integer"},"completeness":{"default":0,"description":"Completeness score","maximum":1,"minimum":0,"title":"Completeness","type":"number"},"consistency":{"default":0,"description":"Consistency score","maximum":1,"minimum":0,"title":"Consistency","type":"integer"}},"title":"ScoresModel","type":"object"},"LegalIDSuggestion":{"description":"Model representing a suggestion for a legal ID.","properties":{"score":{"description":"Confidence score for the suggestion.","maximum":1,"minimum":0,"title":"Score","type":"number"},"account_name":{"description":"The account name","title":"Account Name","type":"string"},"industry":{"anyOf":[{"$ref":"#/components/schemas/IndustryModel"},{"type":"null"}],"default":null,"description":"The industry information"},"website":{"anyOf":[{"$ref":"#/components/schemas/Website"},{"type":"null"}],"default":null,"description":"The website"},"address":{"anyOf":[{"$ref":"#/components/schemas/LegalIDAddress"},{"type":"null"}],"default":null,"description":"The address information"},"financials":{"anyOf":[{"$ref":"#/components/schemas/Financials"},{"type":"null"}],"default":null,"description":"Filed financial figures for the company's most recent fiscal period, as published by its national register. Replaces the former `annual_revenue` field, which is no longer returned."},"employees_nb":{"anyOf":[{"$ref":"#/components/schemas/EmployeesNbModel"},{"type":"null"}],"default":null,"description":"The employee number information"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The source URL","title":"Source"},"company_type":{"anyOf":[{"$ref":"#/components/schemas/CompanyTypeModel"},{"type":"null"}],"default":null,"description":"The company type information"},"date":{"anyOf":[{"$ref":"#/components/schemas/DateModel"},{"type":"null"}],"default":null,"description":"The date information"},"legal_id_type":{"description":"The legal ID type. Free-form: it normally matches one of the types accepted on submission, but a record sourced from the datalake may carry a historical type.","title":"Legal Id Type","type":"string"},"legal_id":{"description":"The legal ID","title":"Legal Id","type":"string"},"headquarters_site":{"anyOf":[{"$ref":"#/components/schemas/HeadquartersSite"},{"type":"null"}],"default":null,"description":"The suggested entity's headquarters site, with its legal identifier — resolved from the datalake's parent link, never from the top of the ownership group. `null` when the record names no parent; the `legal_id` alone is absent when the parent record could not be resolved, and the name then falls back to the one stored inline on the link."}},"required":["score","account_name","legal_id_type","legal_id"],"title":"LegalIDSuggestion","type":"object"},"IndustryModel":{"description":"Model representing industry information.","properties":{"value":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The industry value","title":"Value"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The industry description","title":"Description"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The industry type","title":"Type"}},"title":"IndustryModel","type":"object"},"Website":{"description":"Model representing a website containing a URL.","properties":{"url":{"description":"The URL of the website.","title":"Url","type":"string"}},"required":["url"],"title":"Website","type":"object"},"LegalIDAddress":{"description":"Model representing address information.","properties":{"place_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The place name","title":"Place Name"},"street_number":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"null"}],"default":null,"description":"The street number","title":"Street Number"},"street":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The street name","title":"Street"},"full_street":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The full street address","title":"Full Street"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The city","title":"City"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The state","title":"State"},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The postal code","title":"Postal Code"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The country","title":"Country"},"country_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The country code","title":"Country Code"},"location":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The full location string","title":"Location"}},"title":"LegalIDAddress","type":"object"},"Financials":{"additionalProperties":true,"description":"Filed financial figures for one fiscal period.\n\nAmounts are exactly as filed, in `currency` -- nothing is converted. Which\nfigures are present depends on what the national register publishes: some\nfile a full profit-and-loss, others only a balance sheet.","properties":{"revenue":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}],"default":null,"description":"Revenue / total operating income for the period, in `currency`.","title":"Revenue"},"operating_profit":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}],"default":null,"description":"Operating profit (EBIT-level result) for the period, in `currency`. Only some national registers publish it.","title":"Operating Profit"},"net_income":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}],"default":null,"description":"Net result for the period, after tax, in `currency`.","title":"Net Income"},"equity":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}],"default":null,"description":"Total equity at the end of the period, in `currency`. Only some national registers publish it.","title":"Equity"},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"ISO 4217 currency every amount here is filed in.","title":"Currency"},"fiscal_period":{"anyOf":[{"$ref":"#/components/schemas/FiscalPeriod"},{"type":"null"}],"default":null,"description":"The period the figures cover."},"revenue_range":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Bucketed revenue, in millions of `currency`. No currency conversion is applied, so read it together with `currency`.","title":"Revenue Range"}},"title":"Financials","type":"object"},"FiscalPeriod":{"additionalProperties":true,"description":"The period a set of filed figures covers.","properties":{"start_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"First day of the fiscal period (ISO 8601 date). Not every national register publishes it.","title":"Start Date"},"end_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Last day of the fiscal period (ISO 8601 date).","title":"End Date"}},"title":"FiscalPeriod","type":"object"},"EmployeesNbModel":{"description":"Model representing employee number information.","properties":{"value":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"The employee number value","title":"Value"},"min":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"The minimum number of employees","title":"Min"},"max":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"The maximum number of employees","title":"Max"},"range":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The employee range","title":"Range"}},"title":"EmployeesNbModel","type":"object"},"CompanyTypeModel":{"description":"Model representing company type information.","properties":{"value":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The company type value","title":"Value"},"legal_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The legal type","title":"Legal Type"},"legal_id_type_label":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The legal ID type label","title":"Legal Id Type Label"},"legal_type_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The legal type code","title":"Legal Type Code"}},"title":"CompanyTypeModel","type":"object"},"DateModel":{"description":"Model representing date information.","properties":{"creation_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The creation date","title":"Creation Date"},"closing_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The closing date","title":"Closing Date"},"birth_date":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The birth date","title":"Birth Date"}},"title":"DateModel","type":"object"},"HeadquartersSite":{"additionalProperties":true,"description":"The company's headquarters site, resolved from the datalake parent link.","properties":{"company_name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The headquarters site's company name.","title":"Company Name"},"legal_id":{"anyOf":[{"$ref":"#/components/schemas/HeadquartersLegalId"},{"type":"null"}],"default":null,"description":"The headquarters site's legal identifier. Absent when the parent record could not be resolved in the datalake."}},"title":"HeadquartersSite","type":"object"},"HeadquartersLegalId":{"description":"The headquarters site's legal identifier.","properties":{"value":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The legal identifier value.","title":"Value"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The type of the legal identifier.","title":"Type"}},"title":"HeadquartersLegalId","type":"object"},"Error":{"type":"object","title":"Error","description":"Typed error envelope emitted by the API for handler-level 4xx/5xx responses. Extends the success envelope with a stable machine-readable `code` and a correlation `request_id`.","properties":{"status":{"type":"string","enum":["ERROR"],"description":"Always \"ERROR\" for an error response."},"status_code":{"type":"integer","description":"The HTTP status code of the response."},"message":{"type":"string","description":"Human-readable, PII-free error message."},"code":{"type":"string","enum":["validation_error","unauthorized","payment_required","not_found","conflict","rate_limited","backend_error","backend_timeout","service_unavailable","job_timeout","internal_error","unsupported_registry","idempotency_key_reuse","idempotency_in_progress","idempotency_key_invalid"],"description":"Stable machine-readable error code. `ok` and `job_running` are the success-side codes and never appear in an error body."},"request_id":{"type":"string","description":"API Gateway request id, for support correlation. The same value is returned in the `x-amzn-RequestId` response header on every response, including the 401/403/429 API Gateway generates itself."},"doc_url":{"type":"string","description":"Link to error documentation. Present when error documentation is published."}},"required":["status","status_code","message"],"additionalProperties":true},"GatewayError":{"type":"object","title":"GatewayError","description":"Error body returned by API Gateway itself, before a handler runs: 401 (no or invalid credential), 403 (the API key's scopes do not cover this operation, or the path is not routed here) and 429 (stage throttle; carries `Retry-After`). It has no `code` and no `request_id`; correlate it through the `x-amzn-RequestId` response header instead. A 401 a handler emits after the gateway admitted the request carries the full `Error` envelope.","properties":{"status":{"type":"string","enum":["ERROR"],"description":"Always \"ERROR\"."},"status_code":{"type":"integer","description":"The HTTP status code of the response (401, 403 or 429)."},"message":{"type":"string","description":"Human-readable error message."}},"required":["message"],"additionalProperties":true}},"headers":{"RateLimitLimit":{"description":"Your request allowance for this operation in the current 60-second window. It is counted per credential owner AND per operation: spending it on one operation does not reduce what you may send to another.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Requests still available to you on this operation in the current window. `0` on the request that exhausts it and on the refusals that follow.","schema":{"type":"string"}},"RateLimitReset":{"description":"When the current window resets, as **UTC epoch seconds** — an absolute instant, not a number of seconds to wait. Use `Retry-After` for the delay.","schema":{"type":"string"}},"RateLimit":{"description":"What is left of the allowance, as a structured field of `draft-ietf-httpapi-ratelimit-headers` (an Internet-Draft, not a published standard): `\"<policy>\";r=<remaining>;t=<seconds to reset>`. Exactly one policy governs a request, so the list always carries one member.","schema":{"type":"string"}},"RateLimitPolicy":{"description":"The allowance that governed this request, as a structured field of `draft-ietf-httpapi-ratelimit-headers` (an Internet-Draft, not a published standard): `\"<policy>\";q=<quota>;w=<window seconds>`. `submit` governs submit and synchronous operations, `poll` the poll operations; the policy for each operation is also published in its `x-rate-limit`.","schema":{"type":"string"}},"DelphaMode":{"description":"Present on every response the API renders to a **test-mode** key, and on no other: absence means the call was live. A test-mode call is answered from the published fixture table, reserves no credits and reaches no verification backend. The 401, 403 and shared-floor 429 the gateway answers before the API sees the request carry no per-request headers, so they never carry this one. See the *Test mode* section of this document.","schema":{"type":"string","enum":["sandbox"]}}}},"paths":{"/v1/legal-id/{job_id}":{"get":{"tags":["Legal ID"],"summary":"Get legal ID validation result","description":"Fetch the result of a previously submitted `findAndValidateLegalID` job by `job_id`. On success, the `result` payload contains the normalized legal identifier, the resolved `legal_id_type` (which registry it belongs to), the validity / accuracy scores, a `match` object with the enriched company record (account name, address, annual revenue, employee count, industry, formation date, company type, website) when a confident match is found, and a `suggestions` array of alternative company records each ranked by confidence.","operationId":"getLegalIDResult","responses":{"200":{"description":"Job succeeded — the result payload is populated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalIDPullOutput"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"202":{"description":"Accepted / still running — poll the result route with the returned job_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalIDPullOutput"}}},"headers":{"Location":{"description":"Poll URL for this job (present when the response carries a job_id).","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before polling again.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"400":{"description":"Validation error — the request body or query parameters were rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"401":{"description":"Authentication failed — invalid or missing OAuth 2.0 token or API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}},"headers":{}},"403":{"description":"Forbidden — the credential is valid but not allowed here: the API key's scopes do not cover this operation, or the operation is not routed in this environment (API Gateway then answers `Missing Authentication Token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}},"headers":{}},"404":{"description":"Not found — no job exists for this id, or it belongs to another team.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"409":{"description":"Conflict — the credit reservation expired before delivery; resubmit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"429":{"description":"Too many requests — one of two limits was exceeded. Your allowance for this operation in the current 60-second window: an `Error` body with `code: rate_limited`, `Retry-After` set to the seconds left in the window, and the quota headers with `X-RateLimit-Remaining: 0`; nothing is charged. Or the per-operation floor every caller of that operation shares: a `GatewayError` body with `Retry-After: 1` and no quota headers, refused before the API sees the request.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying: the time left in your current window on the allowance refusal, and `1` on the shared per-operation floor.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"RateLimit":{"$ref":"#/components/headers/RateLimit","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no per-request headers."}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"503":{"description":"Service unavailable — a downstream dependency was unreachable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"504":{"description":"Gateway timeout — the job exceeded its processing ceiling.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}}},"parameters":[{"name":"job_id","in":"path","required":true,"description":"Opaque job identifier returned by `findAndValidateLegalID`.","schema":{"type":"string"}}]}}}}
```

## Submit a batch of legal ID items

> Submit 1..100 legal ID items for asynchronous batch processing as ONE job (never a per-item fan-out). Returns a \`job\_id\` immediately (202); poll \`GET /v1/legal-id/batch/{job\_id}\` for status and results. Each item is validated identically to the single-route \`POST /v1/legal-id\` payload; a payload with 0 items or more than 100 is rejected with 422. A batch in which ANY item names a registry (or a country with no registry) outside the \`legal\_id\_type\` enum is refused as a whole with 422 \`unsupported\_registry\` before any credit is reserved; the message lists the offending item positions and the supported countries.

```json
{"openapi":"3.1.0","info":{"title":"Delpha Data Quality API","version":"2.0.0"},"tags":[{"name":"Legal ID","description":"Legal identifiers are the foundation of corporate trust and compliance—yet they often vary in format and structure from one country to another.\nDelpha's **Legal ID Finder** and **Legal ID Validator** simplify the verification and normalization of company registration numbers worldwide, ensuring your records remain consistent, authentic, and enriched with reliable context.\n\nEach request is assessed through several key dimensions:\n- **Completeness:** Detects missing or incomplete identifiers and, when possible, infers the ID type from the provided country.\n- **Validity:** Confirms that the ID follows the official structure and exists within Delpha's trusted registry for supported countries (see documentation for full coverage).\n- **Consistency:** Compares your input with its normalized version, applying the appropriate format, padding, and length rules.\n- **Accuracy:** Verifies whether the provided ID matches contextual data such as company name or address.\n\nWhen valid, Delpha returns a **normalized and enriched record** containing structured details like company name, address, website, and industry. If side fields are provided, the **Legal ID Finder** can also deliver **AI-generated recommendations** with confidence scores to help identify the correct registered entity.\n\nWith **Legal ID Finder** and **Legal ID Validator**, you gain a consolidated, cross-country view of legal identifiers—enhancing data quality, reliability, and compliance at scale."}],"servers":[{"url":"https://api.delpha.io","description":"Production API server"}],"security":[{"oauth2":["api/access"]},{"apiKey":[]}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth 2.0 client-credentials flow (machine-to-machine). Token URL: https://secure.delpha.io/oauth2/token. The `api/access` scope is all-access: it grants every operation this document publishes. Per-use-case scoping, per-key credit ceilings and expiry are properties of an API key, not of this flow — use an API key when a credential must be restricted.","flows":{"clientCredentials":{"tokenUrl":"https://secure.delpha.io/oauth2/token","scopes":{"api/access":"Access to the public API"}}}},"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"dlp_","description":"Native Delpha API key. Send it as an HTTP bearer token (`Authorization: Bearer dlp_...`). Keys are issued from the Delpha app (Developer → API keys) and are billed per team against the team's credit balance."}},"schemas":{"BatchSubmitOutput":{"additionalProperties":true,"description":"Response after submitting a batch quality job.","properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Stable machine-readable status/error code (see ErrorCode).","title":"Code"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The API Gateway request id, for support correlation.","title":"Request Id"},"doc_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Link to error documentation (present when published).","title":"Doc Url"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The job ID. Required if status <= 300.","title":"Job Id"},"item_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Number of items accepted in the batch (present on success).","title":"Item Count"},"message":{"description":"The message to return","title":"Message","type":"string"},"status":{"description":"The status of the process","enum":["SUCCESS","ERROR"],"title":"Status","type":"string"},"status_code":{"description":"The status code to return","title":"Status Code","type":"integer"}},"required":["message","status","status_code"],"title":"BatchSubmitOutput","type":"object"},"GatewayError":{"type":"object","title":"GatewayError","description":"Error body returned by API Gateway itself, before a handler runs: 401 (no or invalid credential), 403 (the API key's scopes do not cover this operation, or the path is not routed here) and 429 (stage throttle; carries `Retry-After`). It has no `code` and no `request_id`; correlate it through the `x-amzn-RequestId` response header instead. A 401 a handler emits after the gateway admitted the request carries the full `Error` envelope.","properties":{"status":{"type":"string","enum":["ERROR"],"description":"Always \"ERROR\"."},"status_code":{"type":"integer","description":"The HTTP status code of the response (401, 403 or 429)."},"message":{"type":"string","description":"Human-readable error message."}},"required":["message"],"additionalProperties":true},"Error":{"type":"object","title":"Error","description":"Typed error envelope emitted by the API for handler-level 4xx/5xx responses. Extends the success envelope with a stable machine-readable `code` and a correlation `request_id`.","properties":{"status":{"type":"string","enum":["ERROR"],"description":"Always \"ERROR\" for an error response."},"status_code":{"type":"integer","description":"The HTTP status code of the response."},"message":{"type":"string","description":"Human-readable, PII-free error message."},"code":{"type":"string","enum":["validation_error","unauthorized","payment_required","not_found","conflict","rate_limited","backend_error","backend_timeout","service_unavailable","job_timeout","internal_error","unsupported_registry","idempotency_key_reuse","idempotency_in_progress","idempotency_key_invalid"],"description":"Stable machine-readable error code. `ok` and `job_running` are the success-side codes and never appear in an error body."},"request_id":{"type":"string","description":"API Gateway request id, for support correlation. The same value is returned in the `x-amzn-RequestId` response header on every response, including the 401/403/429 API Gateway generates itself."},"doc_url":{"type":"string","description":"Link to error documentation. Present when error documentation is published."}},"required":["status","status_code","message"],"additionalProperties":true},"LegalIDBatchSubmitInput":{"description":"Batch envelope for `POST /v1/legal-id/batch`: `{\"items\": [...]}` (1..100 items, 422 beyond); each item is shaped exactly like the single-route `POST /v1/legal-id` payload (reused here by $ref as `LegalIDSubmitInput`).","properties":{"items":{"description":"The batch items (1..100), each a single-route input payload.","items":{"$ref":"#/components/schemas/LegalIDSubmitInput"},"maxItems":100,"minItems":1,"title":"Items","type":"array"}},"required":["items"],"title":"LegalIDBatchSubmitInput","type":"object"},"LegalIDSubmitInput":{"description":"Payload to submit a new legal ID quality job.","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Legal or trade name of the entity (e.g. `Delpha`).","title":"Name"},"legal_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Existing legal identifier to validate (e.g. SIRET `88052440000012`). Format is registry-specific; supply `legal_id_type` when the format is ambiguous.","title":"Legal Id"},"legal_id_type":{"anyOf":[{"$ref":"#/components/schemas/LegalIDType"},{"type":"null"}],"default":null,"description":"Registry the `legal_id` belongs to. Closed enum of the registries Delpha can query today (e.g. `FRA - SIRET`, `USA - CIK`); any other value is refused with 422 `unsupported_registry` before any credit is reserved. Required only when the same numeric format exists in multiple registries."},"address":{"anyOf":[{"$ref":"#/components/schemas/AddressInput"},{"type":"null"}],"description":"Postal address of the entity. Used to disambiguate registry lookups by country / region."},"website":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}],"default":null,"description":"Entity website — the domain is used as a country signal during registry resolution.","title":"Website"}},"title":"LegalIDSubmitInput","type":"object"},"LegalIDType":{"description":"The legal ID registries Delpha can currently query.\n\nA request naming a registry outside this list is refused before any credits are\nconsumed.","enum":["FRA - SIRET","FRA - SIREN","NZL - NZBN","AUS - ABN","NOR - ORGANISASJONSNUMMER","CHE - UID","GBR - COMPANY REGISTRATION NUMBER","BEL - ENTERPRISE NUMBER","DEU - HANDELSREGISTERNUMMER","EST - COMMERCIAL REGISTER CODE","IRL - CRO NUMBER","ESP - NIF","NLD - KVK-NUMMER","CAN - CORPORATION-NUMBER","FIN - Y-TUNNUS","SWE - ORGANISATIONSNUMMER","USA - CIK"],"title":"LegalIDType","type":"string"},"AddressInput":{"description":"Model representing an address.","properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The street","title":"Street"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The city","title":"City"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The state","title":"State"},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The zip code","title":"Postal Code"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The country","title":"Country"}},"title":"AddressInput","type":"object"}},"headers":{"RateLimitLimit":{"description":"Your request allowance for this operation in the current 60-second window. It is counted per credential owner AND per operation: spending it on one operation does not reduce what you may send to another.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Requests still available to you on this operation in the current window. `0` on the request that exhausts it and on the refusals that follow.","schema":{"type":"string"}},"RateLimitReset":{"description":"When the current window resets, as **UTC epoch seconds** — an absolute instant, not a number of seconds to wait. Use `Retry-After` for the delay.","schema":{"type":"string"}},"RateLimit":{"description":"What is left of the allowance, as a structured field of `draft-ietf-httpapi-ratelimit-headers` (an Internet-Draft, not a published standard): `\"<policy>\";r=<remaining>;t=<seconds to reset>`. Exactly one policy governs a request, so the list always carries one member.","schema":{"type":"string"}},"RateLimitPolicy":{"description":"The allowance that governed this request, as a structured field of `draft-ietf-httpapi-ratelimit-headers` (an Internet-Draft, not a published standard): `\"<policy>\";q=<quota>;w=<window seconds>`. `submit` governs submit and synchronous operations, `poll` the poll operations; the policy for each operation is also published in its `x-rate-limit`.","schema":{"type":"string"}},"DelphaMode":{"description":"Present on every response the API renders to a **test-mode** key, and on no other: absence means the call was live. A test-mode call is answered from the published fixture table, reserves no credits and reaches no verification backend. The 401, 403 and shared-floor 429 the gateway answers before the API sees the request carry no per-request headers, so they never carry this one. See the *Test mode* section of this document.","schema":{"type":"string","enum":["sandbox"]}}}},"paths":{"/v1/legal-id/batch":{"post":{"tags":["Legal ID"],"summary":"Submit a batch of legal ID items","description":"Submit 1..100 legal ID items for asynchronous batch processing as ONE job (never a per-item fan-out). Returns a `job_id` immediately (202); poll `GET /v1/legal-id/batch/{job_id}` for status and results. Each item is validated identically to the single-route `POST /v1/legal-id` payload; a payload with 0 items or more than 100 is rejected with 422. A batch in which ANY item names a registry (or a country with no registry) outside the `legal_id_type` enum is refused as a whole with 422 `unsupported_registry` before any credit is reserved; the message lists the offending item positions and the supported countries.","operationId":"submitLegalIDBatch","responses":{"202":{"description":"Accepted / still running — poll the result route with the returned job_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchSubmitOutput"}}},"headers":{"Location":{"description":"Poll URL for this job (present when the response carries a job_id).","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before polling again.","schema":{"type":"integer"}},"Idempotent-Replayed":{"description":"Set to 'true' when this 202 replays a previously accepted request with the same Idempotency-Key (no new job, no additional charge).","schema":{"type":"string"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"401":{"description":"Authentication failed — invalid or missing OAuth 2.0 token or API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}},"headers":{}},"402":{"description":"Payment required — the team has insufficient credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"403":{"description":"Forbidden — the credential is valid but not allowed here: the API key's scopes do not cover this operation, or the operation is not routed in this environment (API Gateway then answers `Missing Authentication Token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}},"headers":{}},"409":{"description":"Conflict — the `Idempotency-Key` was already used with a different request body (`idempotency_key_reuse`: use a new key), or the original request with this key is still being processed (`idempotency_in_progress`: retry the same request shortly).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"422":{"description":"Unprocessable entity — the request is well-formed but cannot be processed: a documented size/shape bound was violated (`validation_error`), or a legal-ID request names a registry / country Delpha cannot query (`unsupported_registry` — refused before any credit is reserved; the message lists the supported countries).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"429":{"description":"Too many requests — one of two limits was exceeded. Your allowance for this operation in the current 60-second window: an `Error` body with `code: rate_limited`, `Retry-After` set to the seconds left in the window, and the quota headers with `X-RateLimit-Remaining: 0`; nothing is charged. Or the per-operation floor every caller of that operation shares: a `GatewayError` body with `Retry-After: 1` and no quota headers, refused before the API sees the request.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying: the time left in your current window on the allowance refusal, and `1` on the shared per-operation floor.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"RateLimit":{"$ref":"#/components/headers/RateLimit","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no per-request headers."}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"502":{"description":"Bad gateway — the upstream service returned an error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalIDBatchSubmitInput"}}}}}}}}
```

## Get legal ID batch job status

> Poll a batch of legal ID items submitted via \`POST /v1/legal-id/batch\`. 202 while running (with \`item\_count\`/\`processed\_count\` progress); 200 once SUCCEEDED (with \`counts\`, a presigned \`result\_url\`, and \`result\_data\` inlined when <=1MB); 409 if the credit reservation expired before delivery (resubmit); 500 if the job failed; 504 past the 24h ceiling.

```json
{"openapi":"3.1.0","info":{"title":"Delpha Data Quality API","version":"2.0.0"},"tags":[{"name":"Legal ID","description":"Legal identifiers are the foundation of corporate trust and compliance—yet they often vary in format and structure from one country to another.\nDelpha's **Legal ID Finder** and **Legal ID Validator** simplify the verification and normalization of company registration numbers worldwide, ensuring your records remain consistent, authentic, and enriched with reliable context.\n\nEach request is assessed through several key dimensions:\n- **Completeness:** Detects missing or incomplete identifiers and, when possible, infers the ID type from the provided country.\n- **Validity:** Confirms that the ID follows the official structure and exists within Delpha's trusted registry for supported countries (see documentation for full coverage).\n- **Consistency:** Compares your input with its normalized version, applying the appropriate format, padding, and length rules.\n- **Accuracy:** Verifies whether the provided ID matches contextual data such as company name or address.\n\nWhen valid, Delpha returns a **normalized and enriched record** containing structured details like company name, address, website, and industry. If side fields are provided, the **Legal ID Finder** can also deliver **AI-generated recommendations** with confidence scores to help identify the correct registered entity.\n\nWith **Legal ID Finder** and **Legal ID Validator**, you gain a consolidated, cross-country view of legal identifiers—enhancing data quality, reliability, and compliance at scale."}],"servers":[{"url":"https://api.delpha.io","description":"Production API server"}],"security":[{"oauth2":["api/access"]},{"apiKey":[]}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth 2.0 client-credentials flow (machine-to-machine). Token URL: https://secure.delpha.io/oauth2/token. The `api/access` scope is all-access: it grants every operation this document publishes. Per-use-case scoping, per-key credit ceilings and expiry are properties of an API key, not of this flow — use an API key when a credential must be restricted.","flows":{"clientCredentials":{"tokenUrl":"https://secure.delpha.io/oauth2/token","scopes":{"api/access":"Access to the public API"}}}},"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"dlp_","description":"Native Delpha API key. Send it as an HTTP bearer token (`Authorization: Bearer dlp_...`). Keys are issued from the Delpha app (Developer → API keys) and are billed per team against the team's credit balance."}},"schemas":{"LegalIDBatchPullOutput":{"additionalProperties":true,"description":"Response for `GET /v1/legal-id/batch/{job_id}`. Each `result_data.items[]` entry is keyed to its request item by `dispatch_key` (`{\"record_id\": \"<job_id>#<index>\"}`). On success its `result` is the SAME object `GET /v1/legal-id/{job_id}` returns for a single item. On failure it carries an `error` string instead of `result`.","properties":{"code":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Stable machine-readable status/error code (see ErrorCode).","title":"Code"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The API Gateway request id, for support correlation.","title":"Request Id"},"doc_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Link to error documentation (present when published).","title":"Doc Url"},"message":{"description":"A human-readable message describing the current state or outcome of the job.","title":"Message","type":"string"},"status":{"description":"The status of the process","enum":["SUCCESS","ERROR"],"title":"Status","type":"string"},"status_code":{"description":"The HTTP status code representing the job's current state.","title":"Status Code","type":"integer"},"counts":{"anyOf":[{"$ref":"#/components/schemas/CountsModel"},{"type":"null"}],"default":null,"description":"Item-level outcome counts (present only once the job has completed)."},"result_url":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Presigned URL (1h expiry) to download the full batch result JSON from S3.","title":"Result Url"},"result_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"default":null,"description":"The full batch result JSON, inlined (opaque). Present only when status_code == 200 and the result file is <=1MB; otherwise omitted (fetch `result_url` instead). Shape: `{job_id, usecase, counts, items: [...]}`; its `result` is the SAME object `GET /v1/legal-id/{job_id}` returns for a single item.","title":"Result Data"},"item_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Total number of items in the batch (present while the job is running).","title":"Item Count"},"processed_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Number of items processed so far (present while the job is running; may be absent early in the job's lifecycle).","title":"Processed Count"},"process_time":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"The total time taken to process the job, in seconds.","title":"Process Time"}},"required":["message","status","status_code"],"title":"LegalIDBatchPullOutput","type":"object"},"CountsModel":{"description":"Item-level outcome counts for a completed batch job.","properties":{"total":{"description":"Total number of items submitted.","title":"Total","type":"integer"},"succeeded":{"description":"Number of items that succeeded.","title":"Succeeded","type":"integer"},"failed":{"description":"Number of items that failed.","title":"Failed","type":"integer"}},"required":["total","succeeded","failed"],"title":"CountsModel","type":"object"},"Error":{"type":"object","title":"Error","description":"Typed error envelope emitted by the API for handler-level 4xx/5xx responses. Extends the success envelope with a stable machine-readable `code` and a correlation `request_id`.","properties":{"status":{"type":"string","enum":["ERROR"],"description":"Always \"ERROR\" for an error response."},"status_code":{"type":"integer","description":"The HTTP status code of the response."},"message":{"type":"string","description":"Human-readable, PII-free error message."},"code":{"type":"string","enum":["validation_error","unauthorized","payment_required","not_found","conflict","rate_limited","backend_error","backend_timeout","service_unavailable","job_timeout","internal_error","unsupported_registry","idempotency_key_reuse","idempotency_in_progress","idempotency_key_invalid"],"description":"Stable machine-readable error code. `ok` and `job_running` are the success-side codes and never appear in an error body."},"request_id":{"type":"string","description":"API Gateway request id, for support correlation. The same value is returned in the `x-amzn-RequestId` response header on every response, including the 401/403/429 API Gateway generates itself."},"doc_url":{"type":"string","description":"Link to error documentation. Present when error documentation is published."}},"required":["status","status_code","message"],"additionalProperties":true},"GatewayError":{"type":"object","title":"GatewayError","description":"Error body returned by API Gateway itself, before a handler runs: 401 (no or invalid credential), 403 (the API key's scopes do not cover this operation, or the path is not routed here) and 429 (stage throttle; carries `Retry-After`). It has no `code` and no `request_id`; correlate it through the `x-amzn-RequestId` response header instead. A 401 a handler emits after the gateway admitted the request carries the full `Error` envelope.","properties":{"status":{"type":"string","enum":["ERROR"],"description":"Always \"ERROR\"."},"status_code":{"type":"integer","description":"The HTTP status code of the response (401, 403 or 429)."},"message":{"type":"string","description":"Human-readable error message."}},"required":["message"],"additionalProperties":true}},"headers":{"RateLimitLimit":{"description":"Your request allowance for this operation in the current 60-second window. It is counted per credential owner AND per operation: spending it on one operation does not reduce what you may send to another.","schema":{"type":"string"}},"RateLimitRemaining":{"description":"Requests still available to you on this operation in the current window. `0` on the request that exhausts it and on the refusals that follow.","schema":{"type":"string"}},"RateLimitReset":{"description":"When the current window resets, as **UTC epoch seconds** — an absolute instant, not a number of seconds to wait. Use `Retry-After` for the delay.","schema":{"type":"string"}},"RateLimit":{"description":"What is left of the allowance, as a structured field of `draft-ietf-httpapi-ratelimit-headers` (an Internet-Draft, not a published standard): `\"<policy>\";r=<remaining>;t=<seconds to reset>`. Exactly one policy governs a request, so the list always carries one member.","schema":{"type":"string"}},"RateLimitPolicy":{"description":"The allowance that governed this request, as a structured field of `draft-ietf-httpapi-ratelimit-headers` (an Internet-Draft, not a published standard): `\"<policy>\";q=<quota>;w=<window seconds>`. `submit` governs submit and synchronous operations, `poll` the poll operations; the policy for each operation is also published in its `x-rate-limit`.","schema":{"type":"string"}},"DelphaMode":{"description":"Present on every response the API renders to a **test-mode** key, and on no other: absence means the call was live. A test-mode call is answered from the published fixture table, reserves no credits and reaches no verification backend. The 401, 403 and shared-floor 429 the gateway answers before the API sees the request carry no per-request headers, so they never carry this one. See the *Test mode* section of this document.","schema":{"type":"string","enum":["sandbox"]}}}},"paths":{"/v1/legal-id/batch/{job_id}":{"get":{"tags":["Legal ID"],"summary":"Get legal ID batch job status","description":"Poll a batch of legal ID items submitted via `POST /v1/legal-id/batch`. 202 while running (with `item_count`/`processed_count` progress); 200 once SUCCEEDED (with `counts`, a presigned `result_url`, and `result_data` inlined when <=1MB); 409 if the credit reservation expired before delivery (resubmit); 500 if the job failed; 504 past the 24h ceiling.","operationId":"getLegalIDBatchResult","responses":{"200":{"description":"Job succeeded — the result payload is populated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalIDBatchPullOutput"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"202":{"description":"Accepted / still running — poll the result route with the returned job_id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegalIDBatchPullOutput"}}},"headers":{"Location":{"description":"Poll URL for this job (present when the response carries a job_id).","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before polling again.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"400":{"description":"Validation error — the request body or query parameters were rejected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"401":{"description":"Authentication failed — invalid or missing OAuth 2.0 token or API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}},"headers":{}},"403":{"description":"Forbidden — the credential is valid but not allowed here: the API key's scopes do not cover this operation, or the operation is not routed in this environment (API Gateway then answers `Missing Authentication Token`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}},"headers":{}},"404":{"description":"Not found — no job exists for this id, or it belongs to another team.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"409":{"description":"Conflict — the credit reservation expired before delivery; resubmit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"429":{"description":"Too many requests — one of two limits was exceeded. Your allowance for this operation in the current 60-second window: an `Error` body with `code: rate_limited`, `Retry-After` set to the seconds left in the window, and the quota headers with `X-RateLimit-Remaining: 0`; nothing is charged. Or the per-operation floor every caller of that operation shares: a `GatewayError` body with `Retry-After: 1` and no quota headers, refused before the API sees the request.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/GatewayError"}]}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying: the time left in your current window on the allowance refusal, and `1` on the shared per-operation floor.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"RateLimit":{"$ref":"#/components/headers/RateLimit","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no quota headers."},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode","description":"Present on the allowance refusal only. The shared per-operation floor is refused by the gateway, whose responses carry no per-request headers."}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"503":{"description":"Service unavailable — a downstream dependency was unreachable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}},"504":{"description":"Gateway timeout — the job exceeded its processing ceiling.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimitPolicy"},"X-Delpha-Mode":{"$ref":"#/components/headers/DelphaMode"}}}},"parameters":[{"name":"job_id","in":"path","required":true,"description":"The unique identifier of the legal ID batch job.","schema":{"type":"string"}}]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.delpha.io/delpha-api-and-mcp/api/legal-id.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.