{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-developer-resources/ingrid-api/guides/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Address validation","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"address-validation","__idx":0},"children":["Address validation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An Ingrid API key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A complete address from the customer (see"," ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/address-form"},"children":["rendering the address form"]},")"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-submit-the-address-for-validation","__idx":2},"children":["Step 1: Submit the address for validation"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the customer's address to the validation endpoint:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"Request","header":{"title":"Request","controls":{"copy":{}}},"source":"curl -X POST https://api.ingrid.com/v1/delivery/address/validate \\\n  -H \"Authorization: Bearer <YOUR_API_KEY>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"address\": {\n      \"countryCode\": \"SE\",\n      \"postalCode\": \"11453\",\n      \"addressLines\": [\"Sveavägen 31\"],\n      \"locality\": \"Stockholm\"\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"Response — valid","header":{"title":"Response — valid","controls":{"copy":{}}},"source":"{\n  \"status\": \"valid\",\n  \"candidate\": {\n    \"countryCode\": \"SE\",\n    \"postalCode\": \"11453\",\n    \"addressLines\": [\"Sveavägen 31\"],\n    \"locality\": \"Stockholm\"\n  },\n  \"analysis\": {\n    \"verificationLevel\": \"premise\",\n    \"changes\": []\n  },\n  \"fieldReports\": {\n    \"postalCode\": \"match\",\n    \"addressLines\": \"match\",\n    \"locality\": \"match\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-handle-the-result","__idx":3},"children":["Step 2: Handle the result"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," field is a traffic light that tells you what to do:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What your checkout should do"},"children":["What your checkout should do"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["valid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["High-confidence match at premise level. The address is deliverable as-is."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Save the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate"]}," address automatically. No user interaction needed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["suspect"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A match was found, but with significant corrections. The address is"," ","probably deliverable, but the changes should be confirmed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show a \"Did you mean?\" prompt with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate"]},". Let the customer accept"," ","the suggestion or keep their original input."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No deliverable address could be found. The address may have a wrong postal"," ","code, a non-existent street, or missing required fields."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Block form submission. Display an error asking the customer to check their"," ","address."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-suspect-response","__idx":4},"children":["Example: suspect response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"Response — suspect","header":{"title":"Response — suspect","controls":{"copy":{}}},"source":"{\n  \"status\": \"suspect\",\n  \"candidate\": {\n    \"countryCode\": \"SE\",\n    \"postalCode\": \"11453\",\n    \"addressLines\": [\"Sveavägen 31\"],\n    \"locality\": \"Stockholm\"\n  },\n  \"analysis\": {\n    \"verificationLevel\": \"street\",\n    \"changes\": [\"spellingCorrected\"]\n  },\n  \"fieldReports\": {\n    \"postalCode\": \"match\",\n    \"addressLines\": \"fixed\",\n    \"locality\": \"match\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-invalid-response","__idx":5},"children":["Example: invalid response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"Response — invalid","header":{"title":"Response — invalid","controls":{"copy":{}}},"source":"{\n  \"status\": \"invalid\",\n  \"analysis\": {\n    \"verificationLevel\": \"none\",\n    \"changes\": []\n  },\n  \"fieldReports\": {\n    \"postalCode\": \"invalid\",\n    \"addressLines\": \"unknown\",\n    \"locality\": \"unknown\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the status is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid"]},", the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate"]}," field is absent — there is no"," ","corrected address to offer."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"understanding-the-analysis","__idx":6},"children":["Understanding the analysis"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["analysis"]}," object provides detail about how the address was matched."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"verification-level","__idx":7},"children":["Verification level"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The verification level tells you how precisely the address was matched against"," ","reference data:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Level"},"children":["Level"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Confidence"},"children":["Confidence"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["premise"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Matched to exact house or apartment"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Highest"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["street"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Matched to street level, but house number could not be confirmed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Medium"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["locality"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Only matched to city level — street data is poor or missing"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Low"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["none"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No match against reference data"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["None"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"change-types","__idx":8},"children":["Change types"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["changes"]}," array describes what the API corrected:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Change"},"children":["Change"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What happened"},"children":["What happened"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["postalCodeFixed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Postal code was corrected (e.g., transposed digits)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["localityFixed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["City name was corrected or added"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["spellingCorrected"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Street name or other text was spell-corrected"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["componentsAdded"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing components were added from reference data"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["componentsRemoved"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Extraneous components were removed"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"field-reports","__idx":9},"children":["Field reports"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fieldReports"]}," object provides a per-field status. Use it to highlight"," ","specific fields in your form when there are issues:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status"},"children":["Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"UI suggestion"},"children":["UI suggestion"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["match"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Field value is correct"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No action needed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fixed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Field was corrected by the API"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Highlight the field, show the corrected value"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["missing"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Field was empty but expected"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Highlight the field as incomplete"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Field value does not exist in reference data"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Show an error on the field"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unknown"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Field was not checked"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No action needed"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"implementing-did-you-mean","__idx":10},"children":["Implementing \"Did you mean?\""]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the status is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["suspect"]},", present the customer with the corrected"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["candidate"]}," alongside their original input. A common pattern:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Show a banner: \"We adjusted your address. Please confirm.\""]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Display the corrected fields with the changes highlighted"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Offer two buttons: \"Use suggested address\" and \"Keep my address\""]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the customer accepts the suggestion, use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"when-to-validate","__idx":11},"children":["When to validate"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do"]}," validate after the customer completes the address form and before"," ","calling delivery options"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do"]}," validate again if the customer edits their address after initial"," ","validation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do not"]}," validate on every keystroke — wait for form completion"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Do not"]}," block the entire checkout on validation failures — allow the"," ","customer to proceed with a warning if their address is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["suspect"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":12},"children":["Error handling"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error"},"children":["Error"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When it occurs"},"children":["When it occurs"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400 Bad Request"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The request body is malformed or missing required fields"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500 Internal Server Error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server-side issue — retry with exponential backoff"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":13},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/addresses"},"children":["Working with addresses"]}," — overview of the address model and"," ","full flow"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developer-resources/ingrid-api/guides/country-reference"},"children":["Country reference"]}," — understand what \"valid\""," ","means for each country"]}]}]},"headings":[{"value":"Address validation","id":"address-validation","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1: Submit the address for validation","id":"step-1-submit-the-address-for-validation","depth":2},{"value":"Step 2: Handle the result","id":"step-2-handle-the-result","depth":2},{"value":"Example: suspect response","id":"example-suspect-response","depth":3},{"value":"Example: invalid response","id":"example-invalid-response","depth":3},{"value":"Understanding the analysis","id":"understanding-the-analysis","depth":2},{"value":"Verification level","id":"verification-level","depth":3},{"value":"Change types","id":"change-types","depth":3},{"value":"Field reports","id":"field-reports","depth":3},{"value":"Implementing \"Did you mean?\"","id":"implementing-did-you-mean","depth":2},{"value":"When to validate","id":"when-to-validate","depth":2},{"value":"Error handling","id":"error-handling","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Address Validation","description":"How to verify and standardize addresses before creating a delivery order","seo":{"title":"Address validation"}},"lastModified":"2026-02-24T19:14:57.409Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer-resources/ingrid-api/guides/address-validation","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}