{ "openapi": "3.1.0", "info": { "title": "Ingrid API", "description": "The Ingrid API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. You can use the Ingrid API in test mode, which doesn't affect your live data or interact with carrier networks. The API key you use to authenticate the request determines whether the request is live mode or test mode.", "version": "1.0.0", "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0" }, "contact": { "name": "Ingrid Support", "email": "support@ingrid.com" } }, "servers": [ { "url": "https://api.ingrid.com", "description": "Production" } ], "security": [], "tags": [ { "name": "Address", "description": "Address API", "x-displayName": "Address" } ], "paths": { "/v1/address/form": { "get": { "operationId": "getAddressForm", "summary": "Get form configuration", "description": "Get the localized address form configuration for a specific country.\n\nReturns the form fields, validation logic, and visual layout for building\na localized address form dynamically on the client.\n\n## Localization\n\nAll human-readable strings in the response (field `label`s, `hint`s\nand `validationRules[].message`s) along with the resolved\n`meta.language` are translated according to the `Accept-Language` request\nheader. The server selects the best matching locale from the header's\nquality-ranked list. When the header is absent or none of its locales are\nsupported, `en-US` is used.\n\n## Server-Driven UI (SDUI) Pattern\n\nThis endpoint uses a **Server-Driven UI** pattern with a flat schema strategy\nto avoid complex polymorphism. Clients must adhere to the following rules\nwhen rendering:\n\n### 1. Layout-First Rendering\n\nDo not iterate through the `fields` object directly. Iterate through the\n`layout` array instead. The `layout` determines the visual order and grouping\n(rows/columns) of the inputs.\n\n### 2. Conditional Properties\n\nBecause the schema is flat, the `FieldDefinition` object contains properties\nthat may not apply to the current `uiType`:\n\n- **`options`**: ALWAYS ignore unless `uiType === \"select\"`\n- **`keyboard`**: Ignore unless `uiType === \"text\"` (mobile only)\n- **`validationRules`**: If empty or absent, no regex validation is required — only\ncheck the `required` boolean\n\n### 3. State Management\n\nIf the user changes the `countryCode` selection, the client **MUST** discard\nthe current form configuration and fetch this endpoint again with the new\n`countryCode`.", "parameters": [ { "$ref": "#/components/parameters/Common.Localization.AcceptLanguageHeader" }, { "name": "countryCode", "in": "query", "required": true, "description": "ISO 3166-1 alpha-2 country code (e.g., SE, US, GB).", "schema": { "$ref": "#/components/schemas/Address.CountryCode" }, "explode": false }, { "name": "siteId", "in": "query", "required": true, "description": "Site identifier, referring to which site the form configurations are related to.", "schema": { "$ref": "#/components/schemas/Address.SiteId" }, "explode": false }, { "name": "postalCode", "in": "query", "required": false, "description": "Optional postal code. If provided, the response `values` object\nmay contain pre-filled city/state data.", "schema": { "type": "string" }, "explode": false }, { "name": "type", "in": "query", "required": false, "description": "Selects which form configuration to return. When omitted, the delivery\nform is returned. Passing `billing` returns the site-configured billing\nform for the country; if the site has no billing layout, the endpoint\nresponds with a `BadRequestError`.", "schema": { "$ref": "#/components/schemas/Address.FormType" }, "explode": false } ], "responses": { "200": { "description": "A response whose body is localized through `Accept-Language`.", "headers": { "Vary": { "required": true, "schema": { "type": "string", "enum": [ "Accept-Language" ] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address.AddressFormResponse" }, "examples": { "Norwegian address form with postal code lookup": { "summary": "Norwegian address form with postal code lookup", "description": "Returns a localized Norwegian address form with pre-filled city from postal code", "value": { "meta": { "countryCode": "NO", "direction": "ltr", "language": "nb-NO" }, "values": { "locality": "Oslo" }, "fields": { "recipientName": { "label": "Navn", "required": true, "uiType": "text", "keyboard": "default", "autocomplete": "name" }, "addressLines_0": { "label": "Gateadresse", "required": true, "uiType": "text", "keyboard": "default", "autocomplete": "street-address", "hint": "Gatenavn og nummer" }, "addressLines_1": { "label": "c/o", "required": false, "uiType": "text", "prefix": "c/o " }, "postalCode": { "label": "Postnummer", "required": true, "uiType": "text", "keyboard": "numeric", "autocomplete": "postal-code", "validationRules": [ { "regex": "^\\d{4}$", "message": "Oppgi et gyldig postnummer (4 siffer)" } ], "hint": "0154" }, "locality": { "label": "Poststed", "required": true, "uiType": "text", "keyboard": "default", "autocomplete": "address-level2" } }, "layout": [ [ "recipientName" ], [ "addressLines_0" ], [ "addressLines_1" ], [ "postalCode", "locality" ] ] } }, "German address form with postal code lookup": { "summary": "German address form with postal code lookup", "description": "Returns a localized German address form with pre-filled city from postal code", "value": { "meta": { "countryCode": "DE", "direction": "ltr", "language": "de-DE" }, "values": { "locality": "Berlin" }, "fields": { "recipientName": { "label": "Name", "required": true, "uiType": "text", "keyboard": "default", "autocomplete": "name" }, "addressLines_0": { "label": "Straße und Hausnummer", "required": true, "uiType": "text", "keyboard": "default", "autocomplete": "street-address", "hint": "Musterstraße 1" }, "addressLines_1": { "label": "Adresszusatz", "required": false, "uiType": "text", "hint": "Hinterhaus, 3. OG" }, "postalCode": { "label": "Postleitzahl", "required": true, "uiType": "text", "keyboard": "numeric", "autocomplete": "postal-code", "validationRules": [ { "regex": "^\\d{5}$", "message": "Bitte geben Sie eine gültige Postleitzahl ein (5 Ziffern)" } ], "hint": "10117" }, "locality": { "label": "Ort", "required": true, "uiType": "text", "keyboard": "default", "autocomplete": "address-level2" } }, "layout": [ [ "recipientName" ], [ "addressLines_0" ], [ "addressLines_1" ], [ "postalCode", "locality" ] ] } }, "Swedish address form with postal code lookup": { "summary": "Swedish address form with postal code lookup", "description": "Returns a localized Swedish address form with pre-filled city from postal code", "value": { "meta": { "countryCode": "SE", "direction": "ltr", "language": "sv-SE" }, "values": { "locality": "Stockholm", "administrativeArea": "Stockholms län" }, "fields": { "recipientName": { "label": "Namn", "required": true, "uiType": "text", "keyboard": "default", "autocomplete": "name" }, "addressLines_0": { "label": "Adress", "required": true, "uiType": "text", "keyboard": "default", "autocomplete": "street-address", "hint": "Gatunamn och nummer" }, "addressLines_1": { "label": "Care of", "required": false, "uiType": "text", "prefix": "c/o " }, "addressLines_2": { "label": "Våning", "required": false, "uiType": "text", "prefix": "Våning " }, "addressLines_3": { "label": "Lägenhetsnummer", "required": false, "uiType": "text", "prefix": "LGH " }, "postalCode": { "label": "Postnummer", "required": true, "uiType": "text", "keyboard": "numeric", "autocomplete": "postal-code", "validationRules": [ { "regex": "^\\d{3}\\s?\\d{2}$", "message": "Ange ett giltigt postnummer (5 siffror)" } ], "hint": "123 45" }, "locality": { "label": "Ort", "required": true, "uiType": "text", "keyboard": "default", "autocomplete": "address-level2" }, "phoneNumber": { "label": "Telefonnummer", "required": true, "uiType": "text", "keyboard": "phone", "autocomplete": "tel" }, "email": { "label": "E-post", "required": true, "uiType": "text", "keyboard": "email", "autocomplete": "email" } }, "layout": [ [ "recipientName" ], [ "addressLines_0" ], [ "addressLines_1", "addressLines_2", "addressLines_3" ], [ "postalCode", "locality" ], [ "phoneNumber" ], [ "email" ] ] } } } } } }, "400": { "description": "The server could not understand the request due to invalid syntax.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Common.Errors.BadRequestError" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Common.Errors.ServerError" } } } } }, "tags": [ "Address" ], "x-ingrid-authz-permission": "contact.address.get", "x-ingrid-authz-resource-type": "site", "x-ingrid-authz-resource-from": "query", "x-ingrid-authz-resource-param": "siteId", "x-atlas-operation-group": "Forms", "security": [ { "BearerAuth": [] } ] } }, "/v1/address/search": { "get": { "operationId": "autocompleteAddress", "summary": "Search", "description": "Search for addresses or expand a container to drill down into child results.\n\nReturns a list of address predictions based on the user's text input or\nhierarchical container expansion.\n\n## The \"Expand vs Resolve\" Pattern\n\nEach prediction in the response has an `action` field that determines\nthe next step:\n\n- **`resolve`**: The prediction is a final address. Call\n`GET /v1/address/details/{id}` with the prediction's `id` to\nget the full address.\n- **`expand`**: The prediction is a container (e.g., a building with\nmultiple units). Call this endpoint again with `containerId` set to the\nprediction's `id` to fetch the children.\n\n## Usage Modes\n\n1. **Text Search**: Provide `query` with the user's typed text. Results\nare ranked by relevance.\n2. **Container Drill-Down**: Provide `containerId` from a previous\nprediction (where `action` was `expand`). The `query` parameter is\nignored in this mode.\n3. **Field-Specific Search**: Use the `focus` parameter to optimize\nresults for the field being edited (e.g., `postalCode` triggers postal\ndatabase lookups in supported countries).", "parameters": [ { "name": "countryCode", "in": "query", "required": true, "description": "ISO 3166-1 alpha-2 country code.", "schema": { "$ref": "#/components/schemas/Address.CountryCode" }, "explode": false }, { "name": "siteId", "in": "query", "required": true, "description": "Site identifier, referring to which site the autocompletion is performed for.", "schema": { "$ref": "#/components/schemas/Address.SiteId" }, "explode": false }, { "name": "query", "in": "query", "required": false, "description": "The text typed by the user. Ignored if `containerId` is provided.", "schema": { "type": "string" }, "explode": false }, { "name": "containerId", "in": "query", "required": false, "description": "The ID of a parent result (where `action` was `expand`).\nUsed to fetch children (e.g., units in a building).", "schema": { "type": "string" }, "explode": false }, { "name": "focus", "in": "query", "required": false, "description": "The field the user is currently editing. Helps the API optimize results.\nFor example, if `focus` is `postalCode` and the country is GB, the API\nsearches the PAF database.", "schema": { "$ref": "#/components/schemas/Address.AutocompleteFocus" }, "explode": false } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address.SearchAddressesResponse" }, "examples": { "Text search for Dutch addresses": { "summary": "Text search for Dutch addresses", "description": "Returns street containers and resolvable addresses in the Netherlands", "value": { "predictions": [ { "id": "grp_street_nld_2201", "label": "Keizersgracht", "secondaryLabel": "Amsterdam, 1017", "action": "expand", "count": 150, "type": "street" }, { "id": "addr_nld_50123456", "label": "Keizersgracht 585", "secondaryLabel": "Amsterdam, 1017 DR", "action": "resolve", "type": "streetAddress" } ] } }, "Text search for German addresses": { "summary": "Text search for German addresses", "description": "Returns a mix of expandable street containers and resolvable addresses in Germany", "value": { "predictions": [ { "id": "grp_street_deu_4501", "label": "Friedrichstraße", "secondaryLabel": "Berlin, 10117", "action": "expand", "count": 85, "type": "street" }, { "id": "addr_deu_30198765", "label": "Friedrichstraße 43", "secondaryLabel": "Berlin, 10117", "action": "resolve", "type": "streetAddress" } ] } }, "Expand a street container": { "summary": "Expand a street container", "description": "Drills down into a street group to show individual addresses", "value": { "predictions": [ { "id": "addr_gbr_10045832", "label": "10 Buckingham Road", "secondaryLabel": "Redcar, TS10 3JQ", "action": "resolve", "type": "streetAddress" }, { "id": "addr_gbr_10045833", "label": "12 Buckingham Road", "secondaryLabel": "Redcar, TS10 3JQ", "action": "resolve", "type": "streetAddress" } ] } }, "Text search for UK addresses": { "summary": "Text search for UK addresses", "description": "Returns a mix of expandable street containers and resolvable addresses matching the query", "value": { "predictions": [ { "id": "grp_street_882", "label": "Buckingham Road", "secondaryLabel": "Redcar, TS10", "action": "expand", "count": 60, "type": "street" }, { "id": "addr_gbr_20011234", "label": "1 Buckingham Palace Road", "secondaryLabel": "London, SW1W 0QP", "action": "resolve", "type": "streetAddress" } ] } } } } } }, "400": { "description": "The server could not understand the request due to invalid syntax.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Common.Errors.BadRequestError" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Common.Errors.ServerError" } } } } }, "tags": [ "Address" ], "x-ingrid-authz-permission": "contact.address.get", "x-ingrid-authz-resource-type": "site", "x-ingrid-authz-resource-from": "query", "x-ingrid-authz-resource-param": "siteId", "x-atlas-operation-group": "Autocomplete", "security": [ { "BearerAuth": [] } ] } }, "/v1/address/details/{id}": { "get": { "operationId": "getAddressDetails", "summary": "Get details", "description": "Get the full address details for a prediction.\n\nExchanges a prediction ID (where `action` was `resolve`) for a full,\nformatted address object that can be used to populate the\naddress form fields.\n\nThis is the second step of the autocomplete flow — called after the user\nselects a final address prediction from the autocomplete results.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The opaque identifier from a prediction (where `action` was `resolve`).", "schema": { "type": "string" } }, { "name": "siteId", "in": "query", "required": true, "description": "Site identifier, referring to which site the address is resolved for.", "schema": { "$ref": "#/components/schemas/Address.SiteId" }, "explode": false } ], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address.AddressDetailsResponse" }, "examples": { "Resolve a French address prediction": { "summary": "Resolve a French address prediction", "description": "Returns the full address for a resolved French prediction ID", "value": { "address": { "countryCode": "FR", "postalCode": "75001", "addressLines": [ "15 Rue de Rivoli" ], "locality": "Paris" } } }, "Resolve a German address prediction": { "summary": "Resolve a German address prediction", "description": "Returns the full address for a resolved German prediction ID", "value": { "address": { "countryCode": "DE", "postalCode": "10117", "addressLines": [ "Friedrichstraße 43" ], "locality": "Berlin" } } }, "Resolve a UK address prediction": { "summary": "Resolve a UK address prediction", "description": "Returns the full address for a resolved prediction ID", "value": { "address": { "countryCode": "GB", "postalCode": "TS10 3JQ", "addressLines": [ "10 Buckingham Road" ], "locality": "Redcar", "administrativeArea": "Redcar and Cleveland" } } } } } } }, "400": { "description": "The server could not understand the request due to invalid syntax.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Common.Errors.BadRequestError" } } } }, "404": { "description": "The server cannot find the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Common.Errors.NotFoundError" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Common.Errors.ServerError" } } } } }, "tags": [ "Address" ], "x-ingrid-authz-permission": "contact.address.get", "x-ingrid-authz-resource-type": "site", "x-ingrid-authz-resource-from": "query", "x-ingrid-authz-resource-param": "siteId", "x-atlas-operation-group": "Autocomplete", "security": [ { "BearerAuth": [] } ] } }, "/v1/address/validate": { "post": { "operationId": "validateAddress", "summary": "Verify and standardize", "description": "Verify and standardize an address.\n\nTakes a raw address object, matches it against official postal reference\ndata (e.g., USPS, PostNord, Royal Mail), and returns a cleaned, verified\nversion along with quality analysis.\n\n## Response Handling\n\nThe `status` field acts as a traffic light for UI logic:\n\n| Status | Action |\n|--------|--------|\n| `valid` | High confidence match. Save the `candidate` address automatically. |\n| `suspect` | Match found with significant changes. Prompt the user: \"Did you mean...?\" |\n| `invalid` | No deliverable address found. Block form submission. |\n\n## Field Reports\n\nThe optional `fieldReports` dictionary provides per-field status that can\nbe used to highlight specific inputs in the UI (e.g., a red border around\nthe postal code field if it was corrected or invalid).", "parameters": [], "responses": { "200": { "description": "The request has succeeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address.ValidationResult" }, "examples": { "Validate an Italian address with postal code correction": { "summary": "Validate an Italian address with postal code correction", "description": "Submits an Italian address with a wrong postal code and missing province, receives corrected version", "value": { "status": "suspect", "candidate": { "countryCode": "IT", "postalCode": "00187", "addressLines": [ "Via del Corso 1" ], "locality": "Roma", "administrativeArea": "RM" }, "analysis": { "verificationLevel": "premise", "changes": [ "postalCodeFixed", "componentsAdded" ] }, "fieldReports": { "postalCode": "fixed", "addressLines": "match", "locality": "match", "administrativeArea": "match" } } }, "Validate a correct German address": { "summary": "Validate a correct German address", "description": "Submits a correctly formatted address that passes validation with no changes needed", "value": { "status": "valid", "candidate": { "countryCode": "DE", "postalCode": "10117", "addressLines": [ "Friedrichstraße 43" ], "locality": "Berlin" }, "analysis": { "verificationLevel": "premise" }, "fieldReports": { "postalCode": "match", "addressLines": "match", "locality": "match" } } }, "Validate a Swedish address with corrections": { "summary": "Validate a Swedish address with corrections", "description": "Submits a misspelled address and receives back the corrected, standardized version with field-level reports", "value": { "status": "suspect", "candidate": { "countryCode": "SE", "postalCode": "111 22", "addressLines": [ "Sveavägen 1" ], "locality": "Stockholm", "administrativeArea": "Stockholms län" }, "analysis": { "verificationLevel": "premise", "changes": [ "postalCodeFixed", "spellingCorrected", "componentsAdded" ] }, "fieldReports": { "postalCode": "fixed", "addressLines": "fixed", "locality": "fixed", "administrativeArea": "match" } } } } } } }, "400": { "description": "The server could not understand the request due to invalid syntax.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Common.Errors.BadRequestError" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Common.Errors.ServerError" } } } } }, "tags": [ "Address" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Address.ValidateAddressRequest" }, "examples": { "Validate an Italian address with postal code correction": { "summary": "Validate an Italian address with postal code correction", "description": "Submits an Italian address with a wrong postal code and missing province, receives corrected version", "value": { "siteId": "00000000-0000-0000-0000-000000000000", "address": { "countryCode": "IT", "postalCode": "00186", "addressLines": [ "Via del Corso 1" ], "locality": "Roma" } } }, "Validate a correct German address": { "summary": "Validate a correct German address", "description": "Submits a correctly formatted address that passes validation with no changes needed", "value": { "siteId": "00000000-0000-0000-0000-000000000000", "address": { "countryCode": "DE", "postalCode": "10117", "addressLines": [ "Friedrichstraße 43" ], "locality": "Berlin" } } }, "Validate a Swedish address with corrections": { "summary": "Validate a Swedish address with corrections", "description": "Submits a misspelled address and receives back the corrected, standardized version with field-level reports", "value": { "siteId": "00000000-0000-0000-0000-000000000000", "address": { "countryCode": "SE", "postalCode": "11122", "addressLines": [ "Sveavegen 1" ], "locality": "Stokholm" } } } } } } }, "x-ingrid-authz-permission": "contact.address.get", "x-ingrid-authz-resource-type": "site", "x-ingrid-authz-resource-from": "body", "x-ingrid-authz-resource-param": "siteId", "x-atlas-operation-group": "Validate", "security": [ { "BearerAuth": [] } ] } } }, "components": { "schemas": { "Address.Address": { "type": "object", "required": [ "countryCode", "postalCode" ], "properties": { "countryCode": { "$ref": "#/components/schemas/Address.CountryCode", "description": "ISO 3166-1 alpha-2 country code." }, "postalCode": { "type": "string", "description": "Postal code.\nFormatting and validation rules are conditional and based on the country code.", "examples": [ "1017 DR", "75001", "10117", "12345" ] }, "administrativeArea": { "type": "string", "description": "Required for countries:\n##### North America\n* **US** (United States) - *State*\n* **CA** (Canada) - *Province/Territory*\n* **MX** (Mexico) - *State (Estado)*\n\n##### South America\n* **BR** (Brazil) - *State (Estado)* \n* **AR** (Argentina) - *Province*\n\n##### Asia Pacific\n* **AU** (Australia) - *State/Territory*\n* **CN** (China) - *Province*\n* **JP** (Japan) - *Prefecture* \n* **MY** (Malaysia) - *State*\n* **KR** (South Korea) - *Province/City-Province*\n* **ID** (Indonesia) - *Province*\n* **TH** (Thailand) - *Province (Changwat)*\n\n##### Europe\n* **IT** (Italy) - *Province* (2-letter abbreviation like MI, RM)\n* **ES** (Spain) - *Province* \n* **IE** (Ireland) - *County* ", "examples": [ "RM", "Stockholms län" ] }, "subAdministrativeArea": { "type": "string", "description": "Usually the District, Suburb, or Neighborhood.\nTypically not required unless explicitly specified in our documentation." }, "locality": { "type": "string", "description": "The primary locality of the address.\nUsually the City, Town, Village, or Municipality.", "examples": [ "Paris", "Amsterdam", "Berlin", "San Francisco", "Stockholm" ] }, "subLocality": { "type": "string", "description": "The neighborhood, suburb, or district within the locality.\nTypically not required unless explicitly specified in our documentation.\n\nCritical for:\n- Japan (chome/district names)\n- UK (London districts like \"Soho\" or \"Brixton\")\n- Latin America (colonia)" }, "addressLines": { "type": "array", "items": { "type": "string" }, "description": "An ordered array of street address lines.\nIndex 0: Primary street info (Street name + Number, or Block number).\nIndex 1+: Secondary info (Apartment, Suite, Floor, Building Name).", "examples": [ [ "Keizersgracht 585" ], [ "15 Rue de Rivoli" ], [ "Friedrichstraße 43" ], [ "Gatan 1", "1602" ], [ "123 Market Street", "Floor 2, Apt 4B" ], [ "Sveavägen 1" ] ] }, "type": { "$ref": "#/components/schemas/Address.AddressType" } }, "description": "Represents a physical location in a global context.\nDesigned to be generic enough for international addressing standards\n\nValidation is conditional and based on the country code." }, "Address.AddressChange": { "type": "string", "enum": [ "postalCodeFixed", "localityFixed", "spellingCorrected", "componentsAdded", "componentsRemoved" ], "description": "Types of modifications the validation API made to the original address." }, "Address.AddressDetailsResponse": { "type": "object", "required": [ "address" ], "properties": { "address": { "$ref": "#/components/schemas/Address.Address", "description": "The full address resolved from the prediction." } }, "description": "Response containing the full address resolved from a prediction ID." }, "Address.AddressFormResponse": { "type": "object", "required": [ "meta", "fields", "layout" ], "properties": { "meta": { "$ref": "#/components/schemas/Address.FormMeta", "description": "Metadata about the form configuration including locale and text direction." }, "values": { "type": "object", "unevaluatedProperties": { "type": "string" }, "description": "Pre-filled values for the form fields.\nKeys correspond to the keys in the `fields` object.\nThis is often populated if a `postalCode` was sent in the request." }, "fields": { "type": "object", "unevaluatedProperties": { "$ref": "#/components/schemas/Address.FieldDefinition" }, "description": "Dictionary defining the behavior of each input field.\nKeys are unique field identifiers (e.g., `postalCode`, `locality`)." }, "layout": { "type": "array", "items": { "type": "array", "items": { "type": "string" } }, "description": "Defines the visual grid of the form.\nClients should loop through this array to render the UI.\n- Outer array: Rows (stack vertically)\n- Inner array: Columns (stack horizontally / flex)", "examples": [ [ [ "recipientName" ], [ "addressLines" ], [ "postalCode", "locality" ] ] ] } }, "description": "Response containing the complete form configuration for a localized address form.\nIncludes field definitions, validation rules, and visual layout instructions." }, "Address.AddressType": { "type": "string", "enum": [ "unknown", "residential", "commercial" ] }, "Address.AutocompleteFocus": { "type": "string", "enum": [ "addressLines", "postalCode", "locality", "administrativeArea" ], "description": "Indicates which address field the user is currently editing.\nHelps the API optimize results for the relevant field context." }, "Address.CountryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Uppercase ISO 3166-1 alpha-2 country code.", "examples": [ "NO", "ES", "IT", "NL", "FR", "DE", "US", "SE" ] }, "Address.FieldDefinition": { "type": "object", "required": [ "label", "required", "uiType" ], "properties": { "label": { "type": "string", "description": "Localized label text to display above the input.", "examples": [ "City", "Postnummer" ] }, "required": { "type": "boolean", "description": "Whether the client must block submission if this field is empty." }, "uiType": { "$ref": "#/components/schemas/Address.FieldUIType", "description": "Determines the UI component to render." }, "hint": { "type": "string", "description": "Placeholder text (watermark) inside the input.", "examples": [ "123 45" ] }, "keyboard": { "$ref": "#/components/schemas/Address.KeyboardType", "description": "Hint for the virtual keyboard type (mobile only).\nIgnore this field if `uiType` is `select`." }, "autocomplete": { "type": "string", "description": "HTML5 autocomplete attribute value (e.g., `postal-code`, `address-level1`).\nEssential for browser autofill support.", "examples": [ "address-level1", "postal-code" ] }, "prefix": { "type": "string", "description": "Static text prepended to the user's input before submission.", "examples": [ "Våning ", "LGH ", "c/o " ] }, "suffix": { "type": "string", "description": "Static text appended to the user's input before submission.", "examples": [ ". Etage", "F" ] }, "validationRules": { "type": "array", "items": { "$ref": "#/components/schemas/Address.FieldValidationRule" }, "description": "Validation rules for client-side validation.\nIf empty or absent, perform no regex validation — only check the `required` boolean.\nIf present, validate each rule on blur/submit. All rules must pass for the field to be valid." }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/Address.SelectOption" }, "description": "Items for a dropdown/picker.\n- If `uiType` is `select`: This array contains the dropdown items.\n- If `uiType` is `text` or `hidden`: The client **MUST IGNORE** this array." } }, "description": "Defines the properties of a single form input.\n\nThis object is permissive by design (flat schema strategy).\nProperties like `options` or `keyboard` exist on all fields\nbut should be ignored by the client based on the `uiType`.", "examples": [ { "label": "Postleitzahl", "required": true, "uiType": "text", "keyboard": "numeric", "autocomplete": "postal-code", "validationRules": [ { "regex": "^\\d{5}$", "message": "Bitte geben Sie eine gültige Postleitzahl ein (5 Ziffern)" } ], "hint": "10117" }, { "label": "Postnummer", "required": true, "uiType": "text", "keyboard": "numeric", "autocomplete": "postal-code", "validationRules": [ { "regex": "^\\d{3}\\s?\\d{2}$", "message": "Ange ett giltigt postnummer (5 siffror)" } ], "hint": "123 45" } ] }, "Address.FieldReportStatus": { "type": "string", "enum": [ "match", "fixed", "missing", "invalid", "unknown" ], "description": "Per-field validation status, useful for highlighting specific inputs in the UI." }, "Address.FieldUIType": { "type": "string", "enum": [ "text", "select", "hidden" ], "description": "Determines the UI component to render for a form field." }, "Address.FieldValidationRule": { "type": "object", "required": [ "regex", "message" ], "properties": { "regex": { "type": "string", "description": "Regex string for client-side validation.\nValidate on blur/submit.", "examples": [ "^\\d{5}$", "^\\d{3}\\s?\\d{2}$" ] }, "message": { "type": "string", "description": "Localized error message to show if the regex validation fails.", "examples": [ "Bitte geben Sie eine gültige Postleitzahl ein (5 Ziffern)", "Ange ett giltigt postnummer (5 siffror)" ] } }, "description": "A single validation rule for a form field, consisting of a regex pattern and a localized error message." }, "Address.FormMeta": { "type": "object", "required": [ "countryCode", "direction", "language" ], "properties": { "countryCode": { "$ref": "#/components/schemas/Address.CountryCode", "description": "ISO 3166-1 alpha-2 country code for this form configuration." }, "direction": { "$ref": "#/components/schemas/Address.TextDirection", "description": "Text direction. `rtl` (Right-to-Left) is critical for\nlanguages like Arabic or Hebrew." }, "language": { "type": "string", "description": "IETF language tag for the localized labels.", "examples": [ "fr-FR", "nb-NO", "de-DE", "ar-SA", "en-US", "sv-SE" ] } }, "description": "Metadata about the form configuration." }, "Address.FormType": { "type": "string", "enum": [ "delivery", "billing" ], "description": "Selects which address form configuration to return." }, "Address.KeyboardType": { "type": "string", "enum": [ "default", "numeric", "email", "phone" ], "description": "Hint for the virtual keyboard type on mobile devices." }, "Address.Prediction": { "type": "object", "required": [ "id", "label", "action" ], "properties": { "id": { "type": "string", "description": "Opaque identifier. Passed to the details endpoint (if `action` is `resolve`) or back to the autocomplete endpoint as `containerId` (if `action` is `expand`).", "examples": [ "grp_street_882", "addr_gbr_10045832" ] }, "label": { "type": "string", "description": "Primary display text (e.g., \"Buckingham Road\").", "examples": [ "Buckingham Road", "10 Buckingham Road" ] }, "secondaryLabel": { "type": "string", "description": "Secondary display text providing additional context (e.g., \"Redcar, TS10 3JQ\").", "examples": [ "Redcar, TS10 3JQ" ] }, "action": { "$ref": "#/components/schemas/Address.PredictionAction", "description": "Indicates the client action when the user selects this prediction:\n- `resolve`: Leaf node. Call the details endpoint with this prediction's `id`.\n- `expand`: Container node. Call the autocomplete endpoint with `containerId` set to this prediction's `id`." }, "count": { "type": "integer", "format": "int32", "description": "If `action` is `expand`, indicates how many child results are inside this container.\nUseful for UI badges (e.g., \"60 Addresses\").", "examples": [ 60 ] }, "type": { "$ref": "#/components/schemas/Address.PredictionType", "description": "Semantic type of the result, useful for icon selection in the UI." } }, "description": "A single address prediction returned by the autocomplete endpoint.", "examples": [ { "id": "grp_street_fr_1201", "label": "Rue de Rivoli", "secondaryLabel": "Paris, 75001", "action": "expand", "count": 120, "type": "street" }, { "id": "addr_deu_30198765", "label": "Friedrichstraße 43", "secondaryLabel": "Berlin, 10117", "action": "resolve", "type": "streetAddress" }, { "id": "grp_street_882", "label": "Buckingham Road", "secondaryLabel": "Redcar, TS10", "action": "expand", "count": 60, "type": "street" }, { "id": "addr_gbr_10045832", "label": "10 Buckingham Road", "secondaryLabel": "Redcar, TS10 3JQ", "action": "resolve", "type": "streetAddress" } ] }, "Address.PredictionAction": { "type": "string", "enum": [ "resolve", "expand" ], "description": "Indicates the client action when a user selects a prediction." }, "Address.PredictionType": { "type": "string", "enum": [ "streetAddress", "postalCode", "locality", "premise", "street" ], "description": "Semantic type of the prediction result, useful for icon selection in the UI." }, "Address.SearchAddressesResponse": { "type": "object", "required": [ "predictions" ], "properties": { "predictions": { "type": "array", "items": { "$ref": "#/components/schemas/Address.Prediction" }, "description": "List of address predictions matching the search query or container expansion." } }, "description": "Response containing a list of address predictions from the autocomplete endpoint." }, "Address.SelectOption": { "type": "object", "required": [ "label", "value" ], "properties": { "label": { "type": "string", "description": "The human-readable text to display.", "examples": [ "Nordrhein-Westfalen", "Stockholm", "California" ] }, "value": { "type": "string", "description": "The value to submit when this option is selected.", "examples": [ "NW", "SE-AB", "CA" ] } }, "description": "A single option in a select/dropdown field." }, "Address.SiteId": { "type": "string", "minLength": 1, "description": "Identifies an Ingrid site.", "examples": [ "00000000-0000-0000-0000-000000000000" ] }, "Address.TextDirection": { "type": "string", "enum": [ "ltr", "rtl" ], "description": "Text direction for form rendering." }, "Address.ValidateAddressRequest": { "type": "object", "required": [ "siteId", "address" ], "properties": { "siteId": { "$ref": "#/components/schemas/Address.SiteId", "description": "Site identifier, referring to which site we validate the address for." }, "address": { "$ref": "#/components/schemas/Address.Address", "description": "The address to validate against postal reference data." } }, "description": "Request to validate and standardize an address." }, "Address.ValidationAnalysis": { "type": "object", "required": [ "verificationLevel" ], "properties": { "verificationLevel": { "$ref": "#/components/schemas/Address.VerificationLevel", "description": "How granular the match was against reference data." }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/Address.AddressChange" }, "description": "List of modifications the API made to the original address." } }, "description": "Metadata about the quality and granularity of the address match." }, "Address.ValidationResult": { "type": "object", "required": [ "status", "analysis" ], "properties": { "status": { "$ref": "#/components/schemas/Address.ValidationStatus", "description": "High-level validation status for UI logic:\n- `valid`: High confidence match. Save the `candidate` automatically.\n- `suspect`: Match found but with significant changes. Prompt the user \"Did you mean?\".\n- `invalid`: No deliverable address found. Block submission." }, "candidate": { "$ref": "#/components/schemas/Address.Address", "description": "The standardized, corrected address.\nPresent if `status` is `valid` or `suspect`. Absent if `invalid`." }, "analysis": { "$ref": "#/components/schemas/Address.ValidationAnalysis", "description": "Metadata about the quality of the match." }, "fieldReports": { "type": "object", "unevaluatedProperties": { "$ref": "#/components/schemas/Address.FieldReportStatus" }, "description": "Per-field validation status. Keys correspond to address field names.\nUseful for highlighting specific inputs in the UI (e.g., red border on postal code)." } }, "description": "Result of address validation against postal reference data.\nContains the validation status, a standardized candidate address, match analysis,\nand per-field reports for UI highlighting.", "examples": [ { "status": "valid", "candidate": { "countryCode": "DE", "postalCode": "10117", "addressLines": [ "Friedrichstraße 43" ], "locality": "Berlin" }, "analysis": { "verificationLevel": "premise" }, "fieldReports": { "postalCode": "match", "addressLines": "match", "locality": "match" } }, { "status": "suspect", "candidate": { "countryCode": "SE", "postalCode": "111 22", "addressLines": [ "Sveavägen 1" ], "locality": "Stockholm", "administrativeArea": "Stockholms län" }, "analysis": { "verificationLevel": "premise", "changes": [ "postalCodeFixed" ] }, "fieldReports": { "postalCode": "fixed", "locality": "match" } } ] }, "Address.ValidationStatus": { "type": "string", "enum": [ "valid", "suspect", "invalid" ], "description": "High-level validation status for UI logic.\nActs as a traffic light for the address validation result." }, "Address.VerificationLevel": { "type": "string", "enum": [ "premise", "street", "locality", "none" ], "description": "Granularity of the address match against reference data." }, "Common.Errors.BadRequestError": { "type": "object", "required": [ "status", "title", "type" ], "properties": { "status": { "type": "number", "enum": [ 400 ] }, "title": { "type": "string", "enum": [ "Bad Request" ] }, "type": { "type": "string", "enum": [ "https://docs.ingrid.com/developer-resources/ingrid-api/errors/common/bad-request" ] } }, "allOf": [ { "$ref": "#/components/schemas/Common.Errors.ProblemDetails" } ], "examples": [ { "status": 400, "type": "https://docs.ingrid.com/developer-resources/ingrid-api/errors/common/bad-request", "title": "Bad Request", "instance": "urn:ingrid:request:f47ac10b-58cc-4372-a567-0e02b2c3d479" } ] }, "Common.Errors.DetailedError": { "type": "object", "required": [ "code", "detail", "param" ], "properties": { "code": { "type": "string", "description": "A stable, machine-readable error code (and translation key).\ne.g., \"error.email.required\"" }, "detail": { "type": "string", "description": "The final, translated, human-readable message for this specific failure." }, "param": { "type": "string", "format": "json-pointer", "description": "The specific JSON path that caused the error.\ne.g., \"/email\"" } }, "description": "A detailed, machine-readable validation error.\nThis corresponds to the `finalDetailedError` in the Go package." }, "Common.Errors.NotFoundError": { "type": "object", "required": [ "status", "title", "type" ], "properties": { "status": { "type": "number", "enum": [ 404 ] }, "title": { "type": "string", "enum": [ "Not Found" ] }, "type": { "type": "string", "enum": [ "https://docs.ingrid.com/developer-resources/ingrid-api/errors/common/not-found" ] } }, "allOf": [ { "$ref": "#/components/schemas/Common.Errors.ProblemDetails" } ], "examples": [ { "status": 404, "type": "https://docs.ingrid.com/developer-resources/ingrid-api/errors/common/not-found", "title": "Not Found", "instance": "urn:ingrid:request:f47ac10b-58cc-4372-a567-0e02b2c3d479" } ] }, "Common.Errors.ProblemDetails": { "type": "object", "required": [ "type", "title", "status" ], "properties": { "type": { "type": "string", "format": "uri", "description": "A URI reference that identifies the problem type.\nThis MUST link to public documentation.\ne.g., \"https://developer-next.ingrid.com/errors/validation-error\"" }, "title": { "type": "string", "description": "A short, human-readable summary of the problem type (translated).\ne.g., \"Validation Failed\"" }, "status": { "type": "integer", "format": "int32", "description": "The HTTP status code.\ne.g., 400" }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence (translated).\ne.g., \"One or more fields failed validation.\"" }, "instance": { "type": "string", "format": "uri", "description": "A unique identifier for the request that caused the error. Typically to be\nshared with Ingrid support for debugging.", "examples": [ "urn:ingrid:request:f47ac10b-58cc-4372-a567-0e02b2c3d479" ] }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Common.Errors.DetailedError" }, "description": "An array of detailed validation errors.\nThis is omitted if not applicable." } }, "description": "The standard, RFC 9457-compliant error response for our B2B APIs.\nThis corresponds to the `finalProblemDetails` in the Go package." }, "Common.Errors.ServerError": { "type": "object", "required": [ "status", "title", "type" ], "properties": { "status": { "type": "number", "enum": [ 500 ] }, "title": { "type": "string", "enum": [ "Internal Server Error" ] }, "type": { "type": "string", "enum": [ "https://docs.ingrid.com/developer-resources/ingrid-api/errors/common/internal-server-error" ] } }, "allOf": [ { "$ref": "#/components/schemas/Common.Errors.ProblemDetails" } ], "examples": [ { "status": 500, "type": "https://docs.ingrid.com/developer-resources/ingrid-api/errors/common/internal-server-error", "title": "Internal Server Error", "instance": "urn:ingrid:request:f47ac10b-58cc-4372-a567-0e02b2c3d479" } ] } }, "parameters": { "Common.Localization.AcceptLanguageHeader": { "name": "Accept-Language", "in": "header", "required": false, "description": "Selects the locale of the localized, human-readable parts of the\nresponse. When omitted, the endpoint's default locale applies, falling\nback to `en-US`.", "schema": { "type": "string" } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "Bearer" } } }, "x-tagGroups": [ { "name": "Address", "tags": [ "Address" ] } ], "x-ingrid-contract-version": 6 }