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

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.

Submit legal ID for finding and validation

post

Submit an legal ID for finding and validation. Returns a job ID for tracking the process.

Required scopes
This endpoint requires the following scopes:
  • : Access to the public API
Authorizations
OAuth2clientCredentialsRequired

OAuth2 client credentials flow for API access

Token URL:
Body

Payload to submit a new legal ID quality job.

namestring · nullableOptional

The name of the entity

Example: Delpha
legal_idstring · nullableOptional

The legal ID

Example: 88052440000012
legal_id_typestring · enum · nullableOptional

The type of legal ID

Example: FRA - SIRETPossible values:
websitestring · nullableOptional

The website URL

Example: https://delpha.io/
Responses
202

Job submitted to assess_legal_id_v16

application/json

Response after submitting a new legal ID quality job.

job_idstring · nullableOptional

The job ID. Required if status <= 300.

Example: 21014abc65004d2781d2e0ef4c9fbb46
messagestringRequired

The message to return

Example: Job submitted to assess_legal_id_v16
statusstring · enumRequired

The status of the process

Example: SUCCESSPossible values:
status_codeintegerRequired

The status code to return

Example: 202
post/v1/legal-id
POST /v1/legal-id HTTP/1.1
Host: api.delpha.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 224

{
  "name": "Delpha",
  "legal_id": "88052440000012",
  "legal_id_type": "FRA - SIRET",
  "address": {
    "city": "Paris",
    "country": "France",
    "postal_code": "75006",
    "state": "Ile de France",
    "street": "3 AVENUE VAVIN"
  },
  "website": "https://delpha.io/"
}
{
  "job_id": "21014abc65004d2781d2e0ef4c9fbb46",
  "message": "Job submitted to assess_legal_id_v16",
  "status": "SUCCESS",
  "status_code": 202
}

Get legal ID finder and validator job status

get

Retrieve the result and status of a previously submitted legal ID finder and validator job.

Required scopes
This endpoint requires the following scopes:
  • : Access to the public API
Authorizations
OAuth2clientCredentialsRequired

OAuth2 client credentials flow for API access

Token URL:
Path parameters
job_idstringRequired

The unique identifier of the legal ID job

Example: {"summary":"Sample job ID","value":"21014abc65004d2781d2e0ef4c9fbb46"}
Responses
200

Job succeeded.

application/json

Response after retrieving the status and result of an legal ID quality job.

messagestringRequired

A human-readable message describing the current state or outcome of the job.

Example: Job succeeded.
statusstring · enumRequired

The status of the process

Example: SUCCESSPossible values:
status_codeintegerRequired

The HTTP status code representing the job's current state.

Example: 200
process_timenumber · nullableOptional

The total time taken to process the job, in seconds.

Example: 0.123
get/v1/legal-id/{job_id}
GET /v1/legal-id/{job_id} HTTP/1.1
Host: api.delpha.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "message": "Job succeeded.",
  "status": "SUCCESS",
  "status_code": 200,
  "result": {
    "data_type": "legal_id",
    "normalized_value": "88052440000012",
    "label": "OK",
    "legal_id_type": "FRA - SIRET",
    "scores": {
      "validity": 1,
      "completeness": 1,
      "accuracy": 1,
      "consistency": 1
    },
    "match": {
      "score": 1,
      "account_name": "DELPHA",
      "industry": {
        "value": "5112",
        "description": "Software Publishers",
        "type": null
      },
      "website": {
        "url": "https://delpha.io/"
      },
      "address": {
        "place_name": "Wojo",
        "street_number": "3",
        "street": "AV VAVIN",
        "full_street": "3 AV VAVIN",
        "city": "PARIS 6",
        "state": "",
        "postal_code": "75006",
        "country": "FRANCE",
        "country_code": "FR",
        "location": "3 AV VAVIN, PARIS 6, 75006, FRANCE"
      },
      "annual_revenue": {
        "value": "20700000.0",
        "time": "2022",
        "range": "10-50"
      },
      "employees_nb": {
        "value": null,
        "min": 6,
        "max": 9,
        "range": "1-10"
      },
      "source": "https://annuaire-entreprises.data.gouv.fr/entreprise/88052440000012/",
      "company_type": {
        "value": "PME",
        "legal_type": "SAS, société par actions simplifiée",
        "legal_id_type_label": null,
        "legal_type_code": "5710"
      },
      "date": {
        "creation_date": "2020-03-11",
        "closing_date": null,
        "birth_date": null
      },
      "legal_id_type": "FRA - SIRET",
      "legal_id": "88052440000012"
    },
    "suggestions": [
      {
        "score": 1,
        "account_name": "DELPHA",
        "industry": {
          "value": "5112",
          "description": "Software Publishers",
          "type": null
        },
        "website": {
          "url": "https://delpha.io/"
        },
        "address": {
          "place_name": "Wojo",
          "street_number": "3",
          "street": "AV VAVIN",
          "full_street": "3 AV VAVIN",
          "city": "PARIS 6",
          "state": "",
          "postal_code": "75006",
          "country": "FRANCE",
          "country_code": "FR",
          "location": "3 AV VAVIN, PARIS 6, 75006, FRANCE"
        },
        "annual_revenue": {
          "value": "20700000.0",
          "time": "2022",
          "range": "10-50"
        },
        "employees_nb": {
          "value": null,
          "min": 6,
          "max": 9,
          "range": "1-10"
        },
        "source": "https://annuaire-entreprises.data.gouv.fr/entreprise/88052440000012/",
        "company_type": {
          "value": "PME",
          "legal_type": "SAS, société par actions simplifiée",
          "legal_id_type_label": null,
          "legal_type_code": "5710"
        },
        "date": {
          "creation_date": "2020-03-11",
          "closing_date": null,
          "birth_date": null
        },
        "legal_id_type": "FRA - SIRET",
        "legal_id": "88052440000012"
      }
    ]
  },
  "process_time": 0.123
}

Submit a batch of legal ID items

post

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.

Required scopes
This endpoint requires the following scopes:
  • : Access to the public API
Authorizations
OAuth2clientCredentialsRequired

OAuth2 client credentials flow for API access

Token URL:
Body

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).

Responses
202

Batch submitted

application/json

Response after submitting a batch quality job.

job_idstring · nullableOptional

The job ID. Required if status <= 300.

Example: 21014abc65004d2781d2e0ef4c9fbb46
item_countinteger · nullableOptional

Number of items accepted in the batch (present on success).

Example: 100
messagestringRequired

The message to return

Example: Batch submitted
statusstring · enumRequired

The status of the process

Example: SUCCESSPossible values:
status_codeintegerRequired

The status code to return

Example: 202
post/v1/legal-id/batch
POST /v1/legal-id/batch HTTP/1.1
Host: api.delpha.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 236

{
  "items": [
    {
      "name": "Delpha",
      "legal_id": "88052440000012",
      "legal_id_type": "FRA - SIRET",
      "address": {
        "city": "Paris",
        "country": "France",
        "postal_code": "75006",
        "state": "Ile de France",
        "street": "3 AVENUE VAVIN"
      },
      "website": "https://delpha.io/"
    }
  ]
}
{
  "job_id": "21014abc65004d2781d2e0ef4c9fbb46",
  "item_count": 100,
  "message": "Batch submitted",
  "status": "SUCCESS",
  "status_code": 202
}

Get legal ID batch job status

get

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 (batch jobs run on Batch/Vertex timescales, hours not minutes).

Required scopes
This endpoint requires the following scopes:
  • : Access to the public API
Authorizations
OAuth2clientCredentialsRequired

OAuth2 client credentials flow for API access

Token URL:
Path parameters
job_idstringRequired

The unique identifier of the legal ID batch job.

Example: {"summary":"Sample job ID","value":"21014abc65004d2781d2e0ef4c9fbb46"}
Responses
200

97/100 items succeeded

application/json

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.

messagestringRequired

A human-readable message describing the current state or outcome of the job.

Example: 97/100 items succeeded
statusstring · enumRequired

The status of the process

Example: SUCCESSPossible values:
status_codeintegerRequired

The HTTP status code representing the job's current state.

Example: 200
result_urlstring · nullableOptional

Presigned URL (1h expiry) to download the full batch result JSON from S3.

Example: https://delpha-api-batch-dev.s3.amazonaws.com/batch-results/<job_id>.json?...
item_countinteger · nullableOptional

Total number of items in the batch (present while the job is running).

processed_countinteger · nullableOptional

Number of items processed so far (present while the job is running; may be absent early in the job's lifecycle).

process_timenumber · nullableOptional

The total time taken to process the job, in seconds.

Example: 12.3
get/v1/legal-id/batch/{job_id}
GET /v1/legal-id/batch/{job_id} HTTP/1.1
Host: api.delpha.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "message": "97/100 items succeeded",
  "status": "SUCCESS",
  "status_code": 200,
  "counts": {
    "total": 100,
    "succeeded": 97,
    "failed": 3
  },
  "result_url": "https://delpha-api-batch-dev.s3.amazonaws.com/batch-results/<job_id>.json?...",
  "result_data": {
    "job_id": "21014abc65004d2781d2e0ef4c9fbb46",
    "usecase": "legal-id",
    "counts": {
      "total": 2,
      "succeeded": 1,
      "failed": 1
    },
    "items": [
      {
        "dispatch_key": {
          "record_id": "21014abc65004d2781d2e0ef4c9fbb46#0"
        },
        "result": {
          "data_type": "legal_id",
          "normalized_value": "88052440000012",
          "label": "OK",
          "legal_id_type": "FRA - SIRET",
          "scores": {
            "validity": 1,
            "completeness": 1,
            "accuracy": 1,
            "consistency": 1
          },
          "match": {
            "score": 1,
            "account_name": "DELPHA",
            "industry": {
              "value": "5112",
              "description": "Software Publishers",
              "type": null
            },
            "website": {
              "url": "https://delpha.io/"
            },
            "address": {
              "place_name": "Wojo",
              "street_number": "3",
              "street": "AV VAVIN",
              "full_street": "3 AV VAVIN",
              "city": "PARIS 6",
              "state": "",
              "postal_code": "75006",
              "country": "FRANCE",
              "country_code": "FR",
              "location": "3 AV VAVIN, PARIS 6, 75006, FRANCE"
            },
            "annual_revenue": {
              "value": "20700000.0",
              "time": "2022",
              "range": "10-50"
            },
            "employees_nb": {
              "value": null,
              "min": 6,
              "max": 9,
              "range": "1-10"
            },
            "source": "https://annuaire-entreprises.data.gouv.fr/entreprise/88052440000012/",
            "company_type": {
              "value": "PME",
              "legal_type": "SAS, société par actions simplifiée",
              "legal_id_type_label": null,
              "legal_type_code": "5710"
            },
            "date": {
              "creation_date": "2020-03-11",
              "closing_date": null,
              "birth_date": null
            },
            "legal_id_type": "FRA - SIRET",
            "legal_id": "88052440000012"
          },
          "suggestions": [
            {
              "score": 1,
              "account_name": "DELPHA",
              "industry": {
                "value": "5112",
                "description": "Software Publishers",
                "type": null
              },
              "website": {
                "url": "https://delpha.io/"
              },
              "address": {
                "place_name": "Wojo",
                "street_number": "3",
                "street": "AV VAVIN",
                "full_street": "3 AV VAVIN",
                "city": "PARIS 6",
                "state": "",
                "postal_code": "75006",
                "country": "FRANCE",
                "country_code": "FR",
                "location": "3 AV VAVIN, PARIS 6, 75006, FRANCE"
              },
              "annual_revenue": {
                "value": "20700000.0",
                "time": "2022",
                "range": "10-50"
              },
              "employees_nb": {
                "value": null,
                "min": 6,
                "max": 9,
                "range": "1-10"
              },
              "source": "https://annuaire-entreprises.data.gouv.fr/entreprise/88052440000012/",
              "company_type": {
                "value": "PME",
                "legal_type": "SAS, société par actions simplifiée",
                "legal_id_type_label": null,
                "legal_type_code": "5710"
              },
              "date": {
                "creation_date": "2020-03-11",
                "closing_date": null,
                "birth_date": null
              },
              "legal_id_type": "FRA - SIRET",
              "legal_id": "88052440000012"
            }
          ]
        }
      },
      {
        "dispatch_key": {
          "record_id": "21014abc65004d2781d2e0ef4c9fbb46#1"
        },
        "error": "Processing failed for this item."
      }
    ]
  },
  "item_count": null,
  "processed_count": null,
  "process_time": 12.3
}
PreviousNameNextLinked In

Last updated

Was this helpful?