Verify and standardize

Request

Verify and standardize an address.

Takes a raw address object, matches it against official postal reference data (e.g., USPS, PostNord, Royal Mail), and returns a cleaned, verified version along with quality analysis.

Response Handling

The status field acts as a traffic light for UI logic:

Status	Action
`valid`	High confidence match. Save the `candidate` address automatically.
`suspect`	Match found with significant changes. Prompt the user: "Did you mean...?"
`invalid`	No deliverable address found. Block form submission.

Field Reports

The optional fieldReports dictionary provides per-field status that can be used to highlight specific inputs in the UI (e.g., a red border around the postal code field if it was corrected or invalid).

Security

BearerAuth

Bodyapplication/jsonrequired

siteIdstring, non-empty(Address.SiteId)required

Site identifier, referring to which site we validate the address for.

addressobject(Address.Address)required

The address to validate against postal reference data.

Submits an Italian address with a wrong postal code and missing province, receives corrected version

curl -i -X POST \
  https://docs.ingrid.com/_mock/developer-resources/ingrid-api/openapi/v1/address/validate \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "siteId": "00000000-0000-0000-0000-000000000000",
    "address": {
      "countryCode": "IT",
      "postalCode": "00186",
      "addressLines": [
        "Via del Corso 1"
      ],
      "locality": "Roma"
    }
  }'

Responses

The request has succeeded.

Bodyapplication/json

statusstring(Address.ValidationStatus)required

High-level validation status for UI logic:

valid: High confidence match. Save the candidate automatically.
suspect: Match found but with significant changes. Prompt the user "Did you mean?".
invalid: No deliverable address found. Block submission.

Enum:"valid""suspect""invalid"

candidateobject(Address.Address)

The standardized, corrected address. Present if status is valid or suspect. Absent if invalid.

analysisobject(Address.ValidationAnalysis)required

Metadata about the quality of the match.

fieldReportsobject

Per-field validation status. Keys correspond to address field names. Useful for highlighting specific inputs in the UI (e.g., red border on postal code).

Response

Submits an Italian address with a wrong postal code and missing province, receives corrected version

{
  "status": "suspect",
  "candidate": {
    "countryCode": "IT",
    "postalCode": "00187",
    "addressLines": [ … ],
    "locality": "Roma",
    "administrativeArea": "RM"
  },
  "analysis": {
    "verificationLevel": "premise",
    "changes": [ … ]
  },
  "fieldReports": {
    "postalCode": "fixed",
    "addressLines": "match",
    "locality": "match",
    "administrativeArea": "match"
  }
}