Skip to content

Address validation

The validation endpoint checks an address against postal reference data and returns a standardized version. It tells you whether the address is deliverable, what was corrected, and gives you a per-field quality report. Use it after the customer completes the address form and before creating a delivery order.

Prerequisites

Step 1: Submit the address for validation

Send the customer's address to the validation endpoint:

Request
curl -X POST https://api.ingrid.com/v1/delivery/address/validate \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "countryCode": "SE",
      "postalCode": "11453",
      "addressLines": ["Sveavägen 31"],
      "locality": "Stockholm"
    }
  }'
Response — valid
{
  "status": "valid",
  "candidate": {
    "countryCode": "SE",
    "postalCode": "11453",
    "addressLines": ["Sveavägen 31"],
    "locality": "Stockholm"
  },
  "analysis": {
    "verificationLevel": "premise",
    "changes": []
  },
  "fieldReports": {
    "postalCode": "match",
    "addressLines": "match",
    "locality": "match"
  }
}

Step 2: Handle the result

The status field is a traffic light that tells you what to do:

StatusMeaningWhat your checkout should do
validHigh-confidence match at premise level. The address is deliverable as-is.Save the candidate address automatically. No user interaction needed.
suspectA match was found, but with significant corrections. The address is probably deliverable, but the changes should be confirmed.Show a "Did you mean?" prompt with the candidate. Let the customer accept the suggestion or keep their original input.
invalidNo deliverable address could be found. The address may have a wrong postal code, a non-existent street, or missing required fields.Block form submission. Display an error asking the customer to check their address.

Example: suspect response

Response — suspect
{
  "status": "suspect",
  "candidate": {
    "countryCode": "SE",
    "postalCode": "11453",
    "addressLines": ["Sveavägen 31"],
    "locality": "Stockholm"
  },
  "analysis": {
    "verificationLevel": "street",
    "changes": ["spellingCorrected"]
  },
  "fieldReports": {
    "postalCode": "match",
    "addressLines": "fixed",
    "locality": "match"
  }
}

Example: invalid response

Response — invalid
{
  "status": "invalid",
  "analysis": {
    "verificationLevel": "none",
    "changes": []
  },
  "fieldReports": {
    "postalCode": "invalid",
    "addressLines": "unknown",
    "locality": "unknown"
  }
}

When the status is invalid, the candidate field is absent — there is no corrected address to offer.

Understanding the analysis

The analysis object provides detail about how the address was matched.

Verification level

The verification level tells you how precisely the address was matched against reference data:

LevelMeaningConfidence
premiseMatched to exact house or apartmentHighest
streetMatched to street level, but house number could not be confirmedMedium
localityOnly matched to city level — street data is poor or missingLow
noneNo match against reference dataNone

Change types

The changes array describes what the API corrected:

ChangeWhat happened
postalCodeFixedPostal code was corrected (e.g., transposed digits)
localityFixedCity name was corrected or added
spellingCorrectedStreet name or other text was spell-corrected
componentsAddedMissing components were added from reference data
componentsRemovedExtraneous components were removed

Field reports

The fieldReports object provides a per-field status. Use it to highlight specific fields in your form when there are issues:

StatusMeaningUI suggestion
matchField value is correctNo action needed
fixedField was corrected by the APIHighlight the field, show the corrected value
missingField was empty but expectedHighlight the field as incomplete
invalidField value does not exist in reference dataShow an error on the field
unknownField was not checkedNo action needed

Implementing "Did you mean?"

When the status is suspect, present the customer with the corrected candidate alongside their original input. A common pattern:

  1. Show a banner: "We adjusted your address. Please confirm."
  2. Display the corrected fields with the changes highlighted
  3. Offer two buttons: "Use suggested address" and "Keep my address"

If the customer accepts the suggestion, use the candidate for delivery options and order creation. If they decline, proceed with their original input — it may still work, but delivery accuracy could be affected.

When to validate

  • Do validate after the customer completes the address form and before calling delivery options
  • Do validate again if the customer edits their address after initial validation
  • Do not validate on every keystroke — wait for form completion
  • Do not block the entire checkout on validation failures — allow the customer to proceed with a warning if their address is suspect

Error handling

ErrorWhen it occurs
400 Bad RequestThe request body is malformed or missing required fields
500 Internal Server ErrorServer-side issue — retry with exponential backoff

If the validation endpoint is unavailable, allow the customer to proceed without validation. Address issues will surface at order creation if the address is undeliverable.

Next steps

Previous page
Next page