# 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

- An Ingrid API key
- A complete address from the customer (see
[rendering the address form](/developer-resources/ingrid-api/guides/address-form))


## Step 1: Submit the address for validation

Send the customer's address to the validation endpoint:


```bash 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"
    }
  }'
```


```json 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:

| Status | Meaning | What your checkout should do |
|  --- | --- | --- |
| `valid` | High-confidence match at premise level. The address is deliverable as-is. | Save the `candidate` address automatically. No user interaction needed. |
| `suspect` | A 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. |
| `invalid` | No 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


```json 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


```json 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:

| Level | Meaning | Confidence |
|  --- | --- | --- |
| `premise` | Matched to exact house or apartment | Highest |
| `street` | Matched to street level, but house number could not be confirmed | Medium |
| `locality` | Only matched to city level — street data is poor or missing | Low |
| `none` | No match against reference data | None |


### Change types

The `changes` array describes what the API corrected:

| Change | What happened |
|  --- | --- |
| `postalCodeFixed` | Postal code was corrected (e.g., transposed digits) |
| `localityFixed` | City name was corrected or added |
| `spellingCorrected` | Street name or other text was spell-corrected |
| `componentsAdded` | Missing components were added from reference data |
| `componentsRemoved` | Extraneous 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:

| Status | Meaning | UI suggestion |
|  --- | --- | --- |
| `match` | Field value is correct | No action needed |
| `fixed` | Field was corrected by the API | Highlight the field, show the corrected value |
| `missing` | Field was empty but expected | Highlight the field as incomplete |
| `invalid` | Field value does not exist in reference data | Show an error on the field |
| `unknown` | Field was not checked | No 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

| Error | When it occurs |
|  --- | --- |
| `400 Bad Request` | The request body is malformed or missing required fields |
| `500 Internal Server Error` | Server-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

- [Working with addresses](/developer-resources/ingrid-api/guides/addresses) — overview of the address model and
full flow
- [Country reference](/developer-resources/ingrid-api/guides/country-reference) — understand what "valid"
means for each country