Address

Deliverability, territory planning, and compliance all hinge on trustworthy postal data. Delpha's Address Finder and Address Validator keep your address records complete, correct, and standardized—so shipments arrive, analytics stay reliable, and teams can act with confidence.

What you get:

• Completeness: Detects missing parts (number, street, city, postal code, country) and fills gaps when possible.

• Validity: Verifies that addresses exist and follow country-specific postal rules.

• Consistency: Compares your input to its normalized version to surface discrepancies.

• Accuracy: Checks coherence against optional context (e.g., company name, legal ID).

Each request returns a normalized address—standardized and, when possible, enriched. If you provide context like a legal ID or company name, you'll also receive AI-backed recommendations with confidence scores (for example, the registered legal address that best matches your input).

Together, Address Finder and Address Validator transform messy inputs into dependable, action-ready address data.

Submit address for finding and validation

post

Submit an address 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

oauth2

OAuth2clientCredentialsRequired

OAuth2 client credentials flow for API access

Token URL:

Body

application/json

Payload to submit a new address quality job.

addressany ofOptional

The address

Example: {"city":"Paris","country":"France","postal_code":"75006","state":"Ile de France","street":"3 AVENUE VAVIN"}

or

nullOptional

nameany ofOptional

The name of the entity

Example: Delpha

stringOptional

or

nullOptional

legal_idany ofOptional

The legal ID of the entity

Example: 88052440000012

stringOptional

or

nullOptional

linkedinany ofOptional

The LinkedIn URL of the entity

Example: https://www.linkedin.com/company/delphainc/

stringOptional

or

nullOptional

websiteany ofOptional

The website URL of the entity

Example: https://delpha.io/

stringOptional

or

nullOptional

Responses

202

Job submitted to assess_address_v16

application/json

400

Invalid address format or missing required fields

application/json

401

Authentication failed - invalid or missing OAuth 2.0 token

application/json

402

Payment Required

application/json

500

Internal server error

application/json

502

Service unavailable

application/json

post

/v1/address

HTTPcURLJavaScriptPython

POST /v1/address HTTP/1.1
Host: api.delpha.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 251

{
  "address": {
    "city": "Paris",
    "country": "France",
    "postal_code": "75006",
    "state": "Ile de France",
    "street": "3 AVENUE VAVIN"
  },
  "name": "Delpha",
  "legal_id": "88052440000012",
  "linkedin": "https://www.linkedin.com/company/delphainc/",
  "website": "https://delpha.io/"
}

{
  "job_id": "21014abc65004d2781d2e0ef4c9fbb46",
  "message": "Job submitted to assess_address_v16",
  "status": "SUCCESS",
  "status_code": 202
}

Get address finder and validator job status

get

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

Required scopes

This endpoint requires the following scopes:

• : Access to the public API

Authorizations

oauth2

OAuth2clientCredentialsRequired

OAuth2 client credentials flow for API access

Token URL:

Path parameters

job_idstringRequired

The unique identifier of the address job

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

Responses

200

Job succeeded.

application/json

Response after retrieving the status and result of an address 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

resultany ofOptional

The result of the address quality job

Example: {"data_type":"address","label":"Ok","normalized_value":{"city":"Paris","country":"France","full_street":"3 AVE Vavin","place_name":"","postal_code":"75006","state":"Ile-de-France","street":"AVE Vavin","street_number":"3"},"recommendations":[{"address":{"city":"Paris","country":"France","full_street":"3 AVE Vavin","place_name":"","postal_code":"75006","state":"Ile-de-France","street":"AVE Vavin","street_number":"3"},"score":0.996}],"scores":{"accuracy":1,"completeness":1,"consistency":1,"validity":1}}

or

nullOptional

process_timeany ofOptional

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

Example: 0.123

numberOptional

or

nullOptional

202

Job is still running.

application/json

400

Input validation failed.

application/json

401

Authentication failed - invalid or missing OAuth 2.0 token

application/json

500

Failed to retrieve job.

application/json

504

Job timed out.

application/json

get

/v1/address/{job_id}

HTTPcURLJavaScriptPython

GET /v1/address/{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": "address",
    "normalized_value": {
      "street_number": "3",
      "place_name": "",
      "street": "AVE Vavin",
      "full_street": "3 AVE Vavin",
      "city": "Paris",
      "state": "Ile-de-France",
      "postal_code": "75006",
      "country": "France"
    },
    "label": "Ok",
    "scores": {
      "validity": 1,
      "completeness": 1,
      "accuracy": 1,
      "consistency": 1
    },
    "recommendations": [
      {
        "address": {
          "street_number": "3",
          "place_name": "",
          "street": "AVE Vavin",
          "full_street": "3 AVE Vavin",
          "city": "Paris",
          "state": "Ile-de-France",
          "postal_code": "75006",
          "country": "France"
        },
        "score": 0.996
      }
    ]
  },
  "process_time": 0.123
}