The address form endpoint returns everything your client needs to render a localized address form for any supported country — field definitions, validation rules, keyboard hints, and layout. Instead of hardcoding per-country form logic, your client renders what the API tells it to.
- An Ingrid API key
- A country code for the customer's destination (typically from their cart or session)
Call the form endpoint with the customer's country code:
curl -X GET "https://api.ingrid.com/v1/delivery/address/form?countryCode=SE" \
-H "Authorization: Bearer <YOUR_API_KEY>"{
"meta": {
"countryCode": "SE",
"direction": "ltr",
"language": "sv-SE"
},
"fields": {
"postalCode": {
"label": "Postnummer",
"required": true,
"uiType": "text",
"hint": "123 45",
"keyboard": "numeric",
"autocomplete": "postal-code",
"validationRegex": "^\\d{3}\\s?\\d{2}$",
"errorMessage": "Ange ett giltigt postnummer (5 siffror)"
},
"addressLines": {
"label": "Gatuadress",
"required": true,
"uiType": "text",
"hint": "Sveavägen 1",
"keyboard": "default",
"autocomplete": "street-address"
},
"locality": {
"label": "Ort",
"required": true,
"uiType": "text",
"hint": "Stockholm",
"keyboard": "default",
"autocomplete": "address-level2"
}
},
"layout": [
["postalCode"],
["addressLines"],
["locality"]
]
}The response contains three key parts:
| Part | What it is | How to use it |
|---|---|---|
meta | Country, text direction, language | Set text direction on your form container. Use language for locale-aware formatting. |
fields | A dictionary of field definitions keyed by field name | Read label, required, uiType, validationRegex, and other properties per field. |
layout | A 2D grid — outer array is rows, inner array is columns | Iterate this for render order, not fields. Each string references a key in fields. |
Iterate the layout array to determine which fields to render and in what order. Each row in layout is an array of field names that should appear on the same line.
For each field name in layout, look up its definition in fields and render the appropriate UI component:
uiType value | Render as |
|---|---|
text | Text input. Use keyboard for mobile keyboard type and hint for placeholder text. |
select | Dropdown or picker. Populate with the options array from the field definition. |
hidden | Hidden field. Include the value in form submission but do not display. |
Always use layout for rendering order. The fields dictionary is unordered and may contain fields not intended for display in the current layout.
When the customer enters a postal code, re-fetch the form configuration with both countryCode and postalCode. The response may include a values object with pre-filled data:
curl -X GET "https://api.ingrid.com/v1/delivery/address/form?countryCode=SE&postalCode=11453" \
-H "Authorization: Bearer <YOUR_API_KEY>"{
"values": {
"locality": "Stockholm"
}
}When values is present, update the corresponding form fields with the pre-filled data. This saves the customer from typing their city manually.
Not all countries support pre-fill from postal code. If values is absent or empty, leave the fields editable as normal.
Use the validationRegex from each field definition for instant client-side validation before form submission. If validation fails, display the errorMessage from the field definition.
This is a first pass only. For thorough verification against postal reference data, use the address validation endpoint after the customer completes the form.
If the customer changes their country, you MUST re-fetch the form configuration with the new countryCode. Different countries have different fields, layout, validation rules, and languages. Do not cache form configurations across countries.
| Error | When it occurs |
|---|---|
400 Bad Request | Invalid or missing countryCode parameter |
500 Internal Server Error | Server-side issue — retry with exponential backoff |
- Address autocomplete — add type-ahead search to the address form
- Address validation — verify the address before creating an order
- Country reference — country-specific field requirements and formatting rules