Addresses are the starting point for every delivery integration. Before Ingrid can return delivery options, it needs to know where the customer is. This guide explains the address model, the server-driven form system, and how the address endpoints fit into your checkout.
The Ingrid API uses two address models: a base Address for physical locations and a DeliveryAddress that extends it with delivery-specific fields.
The base model for any physical location — warehouses, pickup points, or anywhere you need to represent a place.
ISO 3166-1 alpha-2 country code.
Postal code. Formatting and validation rules are conditional and based on the country code.
Required for countries:
- US (United States) - State
- CA (Canada) - Province/Territory
- MX (Mexico) - State (Estado)
- BR (Brazil) - State (Estado)
- AR (Argentina) - Province
- AU (Australia) - State/Territory
- CN (China) - Province
- JP (Japan) - Prefecture
- MY (Malaysia) - State
- KR (South Korea) - Province/City-Province
- ID (Indonesia) - Province
- TH (Thailand) - Province (Changwat)
- IT (Italy) - Province (2-letter abbreviation like MI, RM)
- ES (Spain) - Province
- IE (Ireland) - County
Usually the District, Suburb, or Neighborhood. Typically not required unless explicitly specified in our documentation.
The primary locality of the address. Usually the City, Town, Village, or Municipality.
The neighborhood, suburb, or district within the locality. Typically not required unless explicitly specified in our documentation.
Critical for:
- Japan (chome/district names)
- UK (London districts like "Soho" or "Brixton")
- Latin America (colonia)
An ordered array of street address lines. Index 0: Primary street info (Street name + Number, or Block number). Index 1+: Secondary info (Apartment, Suite, Floor, Building Name).
countryCode and postalCode are always required. Other fields are conditionally required depending on the country — see the country reference for details.
Extends Address with fields specific to delivering a package to a person. Used for the customer's destination in delivery options and order creation.
ISO 3166-1 alpha-2 country code.
Postal code. Formatting and validation rules are conditional and based on the country code.
Required for countries:
- US (United States) - State
- CA (Canada) - Province/Territory
- MX (Mexico) - State (Estado)
- BR (Brazil) - State (Estado)
- AR (Argentina) - Province
- AU (Australia) - State/Territory
- CN (China) - Province
- JP (Japan) - Prefecture
- MY (Malaysia) - State
- KR (South Korea) - Province/City-Province
- ID (Indonesia) - Province
- TH (Thailand) - Province (Changwat)
- IT (Italy) - Province (2-letter abbreviation like MI, RM)
- ES (Spain) - Province
- IE (Ireland) - County
Usually the District, Suburb, or Neighborhood. Typically not required unless explicitly specified in our documentation.
The primary locality of the address. Usually the City, Town, Village, or Municipality.
The neighborhood, suburb, or district within the locality. Typically not required unless explicitly specified in our documentation.
Critical for:
- Japan (chome/district names)
- UK (London districts like "Soho" or "Brixton")
- Latin America (colonia)
An ordered array of street address lines. Index 0: Primary street info (Street name + Number, or Block number). Index 1+: Secondary info (Apartment, Suite, Floor, Building Name).
Additional instructions for the delivery.
The name of the recipient formatted as expected in the country it's being delivered to.
| Context | Model | Example |
|---|---|---|
| Customer destination | DeliveryAddress | POST /v1/delivery/options, POST /v1/delivery/orders |
| Warehouse / store origin | Address | fulfillmentGroups[].origins[].address |
| Pickup location | Address | Returned in delivery options and POST /v1/delivery/locations |
Instead of hardcoding which address fields to show for each country, you can call the address form endpoint and let the API tell your client what to render.
GET /v1/delivery/address/form?countryCode=SEThe response includes:
- Field definitions — which fields exist, their labels, validation rules, keyboard hints, and whether they are required
- Layout — a grid describing the visual order to render fields
- Pre-filled values — if you also pass
postalCode, the API can pre-fill the city and region
This means your checkout automatically supports new countries without code changes. The API knows that Sweden needs five fields while the United States needs six (including state). Your client just renders what it's told.
See the address form guide for a step-by-step integration.
You only need two fields to get delivery options: countryCode and postalCode. Everything else improves the experience but is not required to get started.
curl -X POST https://api.ingrid.com/v1/delivery/options \
-H "Authorization: Bearer <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"purchaseCountry": "SE",
"purchaseCurrency": "SEK",
"externalRef": "cart-abc-123",
"destination": {
"countryCode": "SE",
"postalCode": "11453"
},
"fulfillmentGroups": [
{
"items": [
{
"quantity": 1,
"weight": { "value": 500, "unit": "g" },
"dimensions": { "length": 30, "width": 20, "height": 10, "unit": "cm" }
}
]
}
]
}'Collect the full street address later — before order creation — and the customer still gets delivery options as soon as they enter their postal code.
The complete address flow has four stages. Each stage is optional except fetching delivery options. Use as many as your checkout needs.
| Stage | Endpoint | Purpose | Required? |
|---|---|---|---|
| Render form | GET /v1/delivery/address/form | Get localized field definitions and layout | No — you can build your own form |
| Autocomplete | GET /v1/delivery/address/search | Type-ahead address suggestions | No — improves UX |
| Validate | POST /v1/delivery/address/validate | Verify and standardize the address | No — recommended before order creation |
| Delivery options | POST /v1/delivery/options | Get available delivery services | Yes |
- Rendering the address form — server-driven form integration
- Address autocomplete — type-ahead search with expand/resolve
- Address validation — verify and standardize addresses
- Country reference — country-specific field requirements and formatting