# Rendering the address form

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.

## Prerequisites

- An Ingrid API key
- A country code for the customer's destination (typically from their cart or
session)


## Overview


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

    C->>I: GET /address/form?countryCode=SE
    I-->>C: fields, layout, validationRules

    Note over C: Render form using layout order

    C->>I: GET /address/form?countryCode=SE&postalCode=11453
    I-->>C: fields + values (locality pre-filled)

    Note over C: Update form with pre-filled values
```

## Step 1: Request the form configuration

Call the form endpoint with the customer's country code:


```bash Request
curl -X GET "https://api.ingrid.com/v1/delivery/address/form?countryCode=SE" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```


```json Response
{
  "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`. |


## Step 2: Render the form

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


Iterate layout, not fields
Always use `layout` for rendering order. The `fields` dictionary is unordered
and may contain fields not intended for display in the current layout.

## Step 3: Pre-fill from postal code

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:


```bash Request
curl -X GET "https://api.ingrid.com/v1/delivery/address/form?countryCode=SE&postalCode=11453" \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```


```json Response (values only)
{
  "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.

## Step 4: Validate client-side

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](/developer-resources/ingrid-api/guides/address-validation) after the
customer completes the form.

## Re-fetch on country change

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 handling

| Error | When it occurs |
|  --- | --- |
| `400 Bad Request` | Invalid or missing `countryCode` parameter |
| `500 Internal Server Error` | Server-side issue — retry with exponential backoff |


## Next steps

- [Address autocomplete](/developer-resources/ingrid-api/guides/address-autocomplete) — add type-ahead search to
the address form
- [Address validation](/developer-resources/ingrid-api/guides/address-validation) — verify the address before
creating an order
- [Country reference](/developer-resources/ingrid-api/guides/country-reference) — country-specific field
requirements and formatting rules