# Working with addresses

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 address model

The Ingrid API uses two address models: a base `Address` for physical locations
and a `DeliveryAddress` that extends it with delivery-specific fields.

### Address

The base model for any physical location — warehouses, pickup points, or
anywhere you need to represent a place.

`countryCode` and `postalCode` are always required. Other fields are
conditionally required depending on the country — see the
[country reference](/developer-resources/ingrid-api/guides/country-reference) for details.

### DeliveryAddress

Extends `Address` with fields specific to delivering a package to a person.
Used for the customer's destination in delivery options and order creation.

### Where each model is used

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


## Server-driven forms

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=SE
```

The 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](/developer-resources/ingrid-api/guides/address-form) for a step-by-step integration.

## The minimum viable 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.


```bash Request
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 full address flow

The complete address flow has four stages. Each stage is optional except
fetching delivery options. Use as many as your checkout needs.


```mermaid
sequenceDiagram
    participant C as Checkout
    participant I as Ingrid API

    Note over C,I: Stage 1: Render the form
    C->>I: GET /address/form?countryCode=SE
    I-->>C: Field definitions, layout, validation rules

    Note over C,I: Stage 2: Autocomplete (optional)
    C->>I: GET /address/search?countryCode=SE&query=Svea
    I-->>C: Predictions
    C->>I: GET /address/details/{id}
    I-->>C: Full DeliveryAddress

    Note over C,I: Stage 3: Validate (recommended)
    C->>I: POST /address/validate
    I-->>C: valid / suspect / invalid + candidate

    Note over C,I: Stage 4: Fetch delivery options
    C->>I: POST /delivery/options
    I-->>C: Delivery groups, categories, services
```

| 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** |


## Related guides

- [Rendering the address form](/developer-resources/ingrid-api/guides/address-form) — server-driven form integration
- [Address autocomplete](/developer-resources/ingrid-api/guides/address-autocomplete) — type-ahead search with expand/resolve
- [Address validation](/developer-resources/ingrid-api/guides/address-validation) — verify and standardize addresses
- [Country reference](/developer-resources/ingrid-api/guides/country-reference) — country-specific field requirements and formatting