Skip to content

Get form configuration

Request

Get the localized address form configuration for a specific country.

Returns the form fields, validation logic, and visual layout for building a localized address form dynamically on the client.

Localization

All human-readable strings in the response (field labels, hints and validationRules[].messages) along with the resolved meta.language are translated according to the Accept-Language request header. The server selects the best matching locale from the header's quality-ranked list. When the header is absent or none of its locales are supported, en-US is used.

Server-Driven UI (SDUI) Pattern

This endpoint uses a Server-Driven UI pattern with a flat schema strategy to avoid complex polymorphism. Clients must adhere to the following rules when rendering:

1. Layout-First Rendering

Do not iterate through the fields object directly. Iterate through the layout array instead. The layout determines the visual order and grouping (rows/columns) of the inputs.

2. Conditional Properties

Because the schema is flat, the FieldDefinition object contains properties that may not apply to the current uiType:

  • options: ALWAYS ignore unless uiType === "select"
  • keyboard: Ignore unless uiType === "text" (mobile only)
  • validationRules: If empty or absent, no regex validation is required — only check the required boolean

3. State Management

If the user changes the countryCode selection, the client MUST discard the current form configuration and fetch this endpoint again with the new countryCode.

Security
BearerAuth
Query
countryCodestring(Address.CountryCode)^[A-Z]{2}$required

ISO 3166-1 alpha-2 country code (e.g., SE, US, GB).

siteIdstring, non-empty(Address.SiteId)required

Site identifier, referring to which site the form configurations are related to.

postalCodestring

Optional postal code. If provided, the response values object may contain pre-filled city/state data.

typestring(Address.FormType)

Selects which form configuration to return. When omitted, the delivery form is returned. Passing billing returns the site-configured billing form for the country; if the site has no billing layout, the endpoint responds with a BadRequestError.

Enum:"delivery""billing"
Headers
Accept-Languagestring

Selects the locale of the localized, human-readable parts of the response. When omitted, the endpoint's default locale applies, falling back to en-US.

curl -i -X GET \
  'https://docs.ingrid.com/_mock/developer-resources/ingrid-api/openapi/v1/address/form?countryCode=NO&siteId=00000000-0000-0000-0000-000000000000&postalCode=string&type=delivery' \
  -H 'Accept-Language: string' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

A response whose body is localized through Accept-Language.

Headers
Varystringrequired
Value:"Accept-Language"
Bodyapplication/json
metaobject(Address.FormMeta)required

Metadata about the form configuration including locale and text direction.

valuesobject

Pre-filled values for the form fields. Keys correspond to the keys in the fields object. This is often populated if a postalCode was sent in the request.

fieldsobjectrequired

Dictionary defining the behavior of each input field. Keys are unique field identifiers (e.g., postalCode, locality).

layoutArray of itemsrequired

Defines the visual grid of the form. Clients should loop through this array to render the UI.

  • Outer array: Rows (stack vertically)
  • Inner array: Columns (stack horizontally / flex)
Response

Returns a localized Norwegian address form with pre-filled city from postal code

{
  "meta": {
    "countryCode": "NO",
    "direction": "ltr",
    "language": "nb-NO"
  },
  "values": {
    "locality": "Oslo"
  },
  "fields": {
    "recipientName": { … },
    "addressLines_0": { … },
    "addressLines_1": { … },
    "postalCode": { … },
    "locality": { … }
  },
  "layout": [
    [ … ],
    [ … ],
    [ … ],
    [ … ]
  ]
}