# 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

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

```json
{"openapi":"3.1.0","info":{"title":"Delpha Data Quality API","version":"1.0.0"},"tags":[{"name":"Address","description":"Deliverability, territory planning, and compliance all hinge on trustworthy postal data.\nDelpha'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.\n\nWhat you get:\n- **Completeness:** Detects missing parts (number, street, city, postal code, country) and fills gaps when possible.\n- **Validity:** Verifies that addresses exist and follow country-specific postal rules.\n- **Consistency:** Compares your input to its normalized version to surface discrepancies.\n- **Accuracy:** Checks coherence against optional context (e.g., company name, legal ID).\n\nEach 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).\n\nTogether, **Address Finder** and **Address Validator** transform messy inputs into dependable, action-ready address data."}],"servers":[{"url":"https://api.delpha.io","description":"Production API server"}],"security":[{"oauth2":["api/access"]}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth2 client credentials flow for API access","flows":{"clientCredentials":{"tokenUrl":"https://secure.delpha.io/oauth2/token","scopes":{"api/access":"Access to the public API"}}}}},"schemas":{"AddressSubmitInput":{"properties":{"address":{"anyOf":[{"$ref":"#/components/schemas/AddressInput"},{"type":"null"}],"description":"The address"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"The name of the entity"},"legal_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Legal Id","description":"The legal ID of the entity"},"linkedin":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Linkedin","description":"The LinkedIn URL of the entity"},"website":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Website","description":"The website URL of the entity"}},"type":"object","title":"AddressSubmitInput","description":"Payload to submit a new address quality job."},"AddressInput":{"properties":{"street":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Street","description":"The street"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"The city"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"The state"},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Postal Code","description":"The zip code"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"The country"}},"type":"object","title":"AddressInput","description":"Model representing an address."},"AddressSubmitOutput":{"properties":{"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id","description":"The job ID. Required if status <= 300."},"message":{"type":"string","title":"Message","description":"The message to return"},"status":{"type":"string","enum":["SUCCESS","ERROR"],"title":"Status","description":"The status of the process"},"status_code":{"type":"integer","title":"Status Code","description":"The status code to return"}},"type":"object","required":["message","status","status_code"],"title":"AddressSubmitOutput","description":"Response after submitting a new address quality job."}}},"paths":{"/v1/address":{"post":{"tags":["Address"],"summary":"Submit address for finding and validation","description":"Submit an address for finding and validation. Returns a job ID for tracking the process.","operationId":"findAndValidateAddress","requestBody":{"description":"\n\n**Validation Rules:**\n\n- **Validation mode:** At least one field in `address` must be provided (street, city, state, postal_code, or country)\n- **Recommendation mode:** One of the following must be provided:\n- `legal_id` and `address.country` (both required together)\n- `name`\n- `website`\n- `linkedin`\n- If both conditions are met, both validation and recommendation will be performed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressSubmitInput"}}},"required":true},"responses":{"202":{"description":"Job submitted to assess_address_v16","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressSubmitOutput"}}}},"400":{"description":"Invalid address format or missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressSubmitOutput"}}}},"401":{"description":"Authentication failed - invalid or missing OAuth 2.0 token","content":{"application/json":{"schema":{"properties":{"message":{"type":"string"}},"type":"object"}}}},"402":{"description":"Payment Required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressSubmitOutput"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressSubmitOutput"}}}},"502":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressSubmitOutput"}}}}}}}}}
```

## Get address finder and validator job status

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

```json
{"openapi":"3.1.0","info":{"title":"Delpha Data Quality API","version":"1.0.0"},"tags":[{"name":"Address","description":"Deliverability, territory planning, and compliance all hinge on trustworthy postal data.\nDelpha'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.\n\nWhat you get:\n- **Completeness:** Detects missing parts (number, street, city, postal code, country) and fills gaps when possible.\n- **Validity:** Verifies that addresses exist and follow country-specific postal rules.\n- **Consistency:** Compares your input to its normalized version to surface discrepancies.\n- **Accuracy:** Checks coherence against optional context (e.g., company name, legal ID).\n\nEach 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).\n\nTogether, **Address Finder** and **Address Validator** transform messy inputs into dependable, action-ready address data."}],"servers":[{"url":"https://api.delpha.io","description":"Production API server"}],"security":[{"oauth2":["api/access"]}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","description":"OAuth2 client credentials flow for API access","flows":{"clientCredentials":{"tokenUrl":"https://secure.delpha.io/oauth2/token","scopes":{"api/access":"Access to the public API"}}}}},"schemas":{"AddressPullOutput":{"properties":{"message":{"type":"string","title":"Message","description":"A human-readable message describing the current state or outcome of the job."},"status":{"type":"string","enum":["SUCCESS","ERROR"],"title":"Status","description":"The status of the process"},"status_code":{"type":"integer","title":"Status Code","description":"The HTTP status code representing the job's current state."},"result":{"anyOf":[{"$ref":"#/components/schemas/AddressModel"},{"type":"null"}],"description":"The result of the address quality job"},"process_time":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Process Time","description":"The total time taken to process the job, in seconds."}},"type":"object","required":["message","status","status_code"],"title":"AddressPullOutput","description":"Response after retrieving the status and result of an address quality job."},"AddressModel":{"properties":{"data_type":{"$ref":"#/components/schemas/DataType","description":"The type of data for this field"},"normalized_value":{"$ref":"#/components/schemas/AddressOutput","description":"Normalized address value."},"label":{"type":"string","enum":["No","Ok","Unknown"],"title":"Label","description":"Label for the address."},"scores":{"$ref":"#/components/schemas/ScoresModel","description":"Scores for the field"},"recommendations":{"items":{"$ref":"#/components/schemas/AddressRecommendation"},"type":"array","title":"Recommendations","description":"Recommendations for the address."}},"type":"object","required":["data_type","normalized_value","label","scores","recommendations"],"title":"AddressModel","description":"Model representing the details of an address field."},"DataType":{"type":"string","enum":["email","social_network","name","legal_id","phone","address","website"],"title":"DataType"},"AddressOutput":{"properties":{"street_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Street Number","description":"The street number"},"place_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Place Name","description":"The place name"},"street":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Street","description":"The street"},"full_street":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Street","description":"The full street"},"city":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"City","description":"The city"},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"The state"},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Postal Code","description":"The zip code"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country","description":"The country"}},"type":"object","title":"AddressOutput","description":"Model representing an address."},"ScoresModel":{"properties":{"accuracy":{"type":"number","maximum":1,"minimum":-1,"title":"Accuracy","description":"Accuracy score","default":-1},"validity":{"type":"integer","maximum":1,"minimum":-1,"title":"Validity","description":"Validity score","default":-1},"completeness":{"type":"number","maximum":1,"minimum":0,"title":"Completeness","description":"Completeness score","default":0},"consistency":{"type":"integer","maximum":1,"minimum":0,"title":"Consistency","description":"Consistency score","default":0}},"type":"object","title":"ScoresModel","description":"Model representing the scores for an email field."},"AddressRecommendation":{"properties":{"address":{"$ref":"#/components/schemas/AddressOutput","description":"Recommended address value."},"score":{"type":"number","maximum":1,"minimum":0,"title":"Score","description":"Confidence score for the recommendation."}},"type":"object","required":["address","score"],"title":"AddressRecommendation","description":"Model representing a recommendation for an address."}}},"paths":{"/v1/address/{job_id}":{"get":{"tags":["Address"],"summary":"Get address finder and validator job status","description":"Retrieve the result and status of a previously submitted address finder and validator job.","operationId":"getAddressResult","responses":{"200":{"description":"Job succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressPullOutput"}}}},"202":{"description":"Job is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressPullOutput"}}}},"400":{"description":"Input validation failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressPullOutput"}}}},"401":{"description":"Authentication failed - invalid or missing OAuth 2.0 token","content":{"application/json":{"schema":{"properties":{"message":{"type":"string"}},"type":"object"}}}},"500":{"description":"Failed to retrieve job.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressPullOutput"}}}},"504":{"description":"Job timed out.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressPullOutput"}}}}}}}}}
```


---

# Agent Instructions: 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:

```
GET https://help.delpha.io/delpha-api-and-mcp/api/address.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.