> For the complete documentation index, see [llms.txt](https://docs.nexusglobalpayments.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexusglobalpayments.org/nexus-payments-apis/address-types.md).

# Address Types

Address types and input field definitions for recipient account or proxy details, by country or address type.

## Gets all the address types AND inputs for a specified Country

> Returns all address types AND their associated inputs for a specified country.\
> \
> \---\
> \
> \#### Response validation rules\
> \
> \*\*200 OK\*\* — the body MUST conform to the response schema below. Response objects are open: additional properties may be introduced in later minor versions, and clients MUST ignore properties they do not recognise.\
> \
> The body is a top-level JSON array (no envelope); it may be empty unless stated otherwise.\
> \
> \| Field | Type | Presence | Nullable | Constraints |\
> \|---|---|---|---|---|\
> \| \`\[].addressTypeId\` | string | Required | N | pattern \`^\[A-Z]+$\`; min length 1; max length 20 |\
> \| \`\[].countries\` | array | Required | N | each item: pattern \`^\[A-Z]{2}$\`, length 2 |\
> \| \`\[].addressTypeCode\` | string | Required | N | min length 1; max length 10 |\
> \| \`\[].clearingSystemId\` | string | Conditional — present when \`addressTypeCode\` is \`ACCT\` or \`IBAN\` | Y | max length 12 |\
> \| \`\[].proxyDirectoryId\` | string | Conditional — present when \`addressTypeCode\` is a proxy type (\`MBNO\`, \`EMAL\`, \`NIDN\`) | Y | max length 20 |\
> \| \`\[].displayOrder\` | integer | Required | N | format \`int32\`; ≥ 1 |\
> \| \`\[].inputs\` | array | Required | N | ≥ 1 item(s) |\
> \| \`\[].inputs\[].addressInputId\` | string | Required | N | min length 1; max length 20 |\
> \| \`\[].inputs\[].label\` | object | Conditional — present for visible inputs; absent for \`hidden\` inputs | Y | — |\
> \| \`\[].inputs\[].label.addressTypeCode\` | string | Required | N | min length 1; max length 10 |\
> \| \`\[].inputs\[].label.title\` | object | Required | N | — |\
> \| \`\[].inputs\[].label.title.en\` | string | Required | N | min length 1; max length 200 |\
> \| \`\[].inputs\[].label.title.de\` | string | Optional | N | — |\
> \| \`\[].inputs\[].attributes\` | object | Required | N | — |\
> \| \`\[].inputs\[].attributes.name\` | string | Required | N | min length 1; max length 50 |\
> \| \`\[].inputs\[].attributes.type\` | string | Required | N | one of \`text\`, \`number\`, \`hidden\`; max length 10 |\
> \| \`\[].inputs\[].attributes.pattern\` | string | Conditional — absent when \`type\` = \`hidden\` | N | max length 200 |\
> \| \`\[].inputs\[].attributes.placeholder\` | string | Conditional — absent when \`type\` = \`hidden\` | N | max length 50 |\
> \| \`\[].inputs\[].attributes.required\` | boolean | Required | N | — |\
> \| \`\[].inputs\[].attributes.value\` | string | Conditional — present only when \`type\` = \`hidden\` | N | max length 50 |\
> \| \`\[].inputs\[].iso20022XPath\` | object | Required | N | — |\
> \| \`\[].inputs\[].iso20022XPath.acmt023\` | string | Required | Y | pattern \`^/Document/.+\`; max length 200 |\
> \| \`\[].inputs\[].iso20022XPath.pacs008\` | string | Required | Y | pattern \`^/Document/.+\`; max length 200 |\
> \
> \*\*Cross-field rules\*\*\
> \
> \- \`addressTypeId\` is unique within the country; \`inputs\[].addressInputId\` is unique within its address type.\
> \- \`clearingSystemId\` is populated for account types (\`ACCT\`, \`IBAN\`) and \`null\` for proxy types; \`proxyDirectoryId\` is populated for proxy types (\`MBNO\`, \`EMAL\`, \`NIDN\`) and \`null\` for account types.\
> \- For inputs with \`attributes.type\` = \`hidden\`: \`label\`, \`attributes.pattern\` and \`attributes.placeholder\` are absent and \`attributes.value\` is present.\
> \- \`attributes.pattern\`, when present, is a valid regular expression.\
> \- \`iso20022XPath.acmt023\` / \`iso20022XPath.pacs008\` are \`null\` when the input is not mapped to that message.\
> \
> \*\*Response signature\*\* — every 200 and 304 response carries \`Signature-Input\` and \`Signature\` (plus \`Content-Digest\` on 200) per the Nexus HTTP Message Signature Profile v1, signed by the responding server. The client MUST verify the response signature before using the response and MUST discard a response that fails verification.\
> \
> \*\*Error responses (4xx/5xx with a body)\*\* — the body MUST conform to \`ErrorApiResponse\`: \`statusCode\` = \`RJCT\`; \`reasonCode\` matches \`^\[A-Z]{2}\[0-9]{3}$\`; \`name\` is UPPER\_SNAKE\_CASE (≤ 50); \`description\` ≤ 500 characters and MUST NOT contain PII. \`reasonCode\` values for this operation: \`TE001\`, \`BE001\`, \`BE002\`, \`TE099\`, \`AE001\`, \`AE002\`, \`AE003\`, \`AE005\`, \`AE006\`, \`AE004\`. Gateway errors (405, 429, 502, 503, 504) carry no body.

```json
{"openapi":"3.1.0","info":{"title":"Nexus Payments API","version":"v1"},"tags":[{"name":"Address Types","description":"Address types and input field definitions for recipient account or proxy details, by country or address type."}],"servers":[{"url":"https://{environment}.payments.nexus.net","description":"Nexus participant-facing API endpoint. Resolved via Nexus private DNS over the established IPsec IKEv2 tunnel and not reachable from the public Internet.","variables":{"environment":{"default":"prod","enum":["pat","prod"],"description":"Deployment environment subdomain."}}}],"security":[{"mutualTLS":[],"nexusOAuth":["address.read"]}],"components":{"securitySchemes":{"mutualTLS":{"type":"mutualTLS","description":"Mutual TLS: the IPSO presents its X.509 client certificate on every connection, validated during the TLS handshake (fail-closed). The same certificate is the RFC 8705 binding anchor for the OAuth access token (see nexusOAuth)."}},"parameters":{"SignatureInputBodyless":{"name":"Signature-Input","in":"header","required":true,"description":"RFC 9421 signature metadata for a request without a body, per the Nexus HTTP Message Signature Profile v1 (RFC 9421, RFC 9530). One dictionary member labelled `nexus` whose covered components are exactly `\"@method\" \"@authority\" \"@path\" \"@query\"`, followed by `\"if-none-match\"` when that header is sent. `@query` is always covered; an empty query serialises as `?`, so query parameters cannot be added or removed undetected. Signature parameters, emitted in this order: `created` and `expires` (Unix seconds; `expires` = `created` + 300; the receiver rejects `created` more than ±5 minutes from its clock or a signature past `expires`), `keyid` (base64url SHA-256 thumbprint of the signer's signing public key, registered at onboarding; a missing, unknown, expired or revoked key id is rejected - never resolved to a default key), `alg` (always `rsa-pss-sha512`) and `tag` (always `nexus-v1`). The signature parameters are signed through the `@signature-params` line of the signature base. A missing, malformed or non-conforming value is rejected with AE005.","schema":{"type":"string","maxLength":512,"pattern":"^nexus=\\(\"@method\" \"@authority\" \"@path\" \"@query\"( \"if-none-match\")?\\);created=[0-9]{1,15};expires=[0-9]{1,15};keyid=\"[A-Za-z0-9_-]{43}\";alg=\"rsa-pss-sha512\";tag=\"nexus-v1\"$"}},"Signature":{"name":"Signature","in":"header","required":true,"description":"RFC 9421 signature value: one dictionary member labelled `nexus` holding an RFC 8941 byte sequence - the **standard base64** (not base64url) RSASSA-PSS signature using SHA-512 (`rsa-pss-sha512`), computed over the RFC 9421 signature base built from the components and parameters declared in `Signature-Input`. Produced with the sender's own signing private key; the receiver verifies it against the sender's registered signing public key resolved from `keyid`. With the minimum RSA-3072 key the signature is 384 bytes, i.e. 512 base64 characters. A missing, malformed or non-verifying signature is rejected with AE005.","schema":{"type":"string","minLength":520,"maxLength":1400,"pattern":"^nexus=:[A-Za-z0-9+/]+={0,2}:$"}}},"headers":{"ResponseSignatureInput":{"description":"RFC 9421 signature metadata for a GET response, per the Nexus HTTP Message Signature Profile v1 (RFC 9421, RFC 9530). Signed by the responding server with its own signing private key. Covered components: `\"@status\" \"content-type\" \"content-digest\"` on 200, or `\"@status\" \"etag\"` on 304, followed in both cases by the request-bound components `\"@method\";req \"@path\";req \"@query\";req`, which tie the response to the resource that was requested. Same `created`, `expires`, `keyid`, `alg` and `tag` rules as requests. The client MUST verify the response signature before using the response and MUST discard a response that fails verification.","required":true,"schema":{"type":"string","maxLength":512,"pattern":"^nexus=\\(\"@status\" (\"content-type\" \"content-digest\"|\"etag\") \"@method\";req \"@path\";req \"@query\";req\\);created=[0-9]{1,15};expires=[0-9]{1,15};keyid=\"[A-Za-z0-9_-]{43}\";alg=\"rsa-pss-sha512\";tag=\"nexus-v1\"$"}},"ResponseSignature":{"description":"RFC 9421 response signature: one dictionary member labelled `nexus` holding the standard base64 `rsa-pss-sha512` signature produced by the responding server over the signature base declared in the response `Signature-Input`. Verified by the client against the server's registered signing public key.","required":true,"schema":{"type":"string","minLength":520,"maxLength":1400,"pattern":"^nexus=:[A-Za-z0-9+/]+={0,2}:$"}},"ResponseContentDigest":{"description":"RFC 9530 SHA-512 digest of the exact response body bytes, covered by the response signature.","required":true,"schema":{"type":"string","pattern":"^sha-512=:[A-Za-z0-9+/]{86}==:$"}}},"schemas":{"AddressTypeWithInputsResponse":{"type":"object","description":"Address type metadata including input definitions.","properties":{"addressTypeId":{"type":"string","description":"Uppercase address type identifier.","pattern":"^[A-Z]+$","minLength":1,"maxLength":20},"countries":{"type":"array","description":"ISO 3166-1 alpha-2 country codes where the address type is supported.","items":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Z]{2}$"}},"addressTypeCode":{"type":"string","description":"Address type code.","minLength":1,"maxLength":10},"clearingSystemId":{"type":["string","null"],"description":"Clearing system identifier.","maxLength":12},"proxyDirectoryId":{"type":["string","null"],"description":"Proxy directory identifier.","maxLength":20},"displayOrder":{"type":"integer","format":"int32","description":"Display order for UI presentation.","minimum":1},"inputs":{"type":"array","description":"Input definitions for the address type.","items":{"$ref":"#/components/schemas/AddressInputResponse"},"minItems":1}},"required":["addressTypeCode","addressTypeId","countries","displayOrder","inputs"]},"AddressInputResponse":{"type":"object","description":"Address input definition.","properties":{"addressInputId":{"type":"string","description":"Address input identifier.","minLength":1,"maxLength":20},"label":{"oneOf":[{"$ref":"#/components/schemas/AddressLabelResponse"},{"type":"null"}],"description":"Localized display label for the input."},"attributes":{"$ref":"#/components/schemas/AddressInputAttributesResponse","description":"Input attributes and validation metadata."},"iso20022XPath":{"$ref":"#/components/schemas/Iso20022XPathResponse","description":"ISO 20022 XPath mappings."}},"required":["addressInputId","attributes","iso20022XPath"]},"AddressLabelResponse":{"type":"object","description":"Localized label for an address input.","properties":{"addressTypeCode":{"type":"string","description":"Address type code.","minLength":1,"maxLength":10},"title":{"$ref":"#/components/schemas/LocalizedTitleResponse","description":"Localized title text."}},"required":["addressTypeCode","title"]},"LocalizedTitleResponse":{"type":"object","description":"Localized title values.","properties":{"en":{"type":"string","description":"English label.","minLength":1,"maxLength":200},"de":{"type":"string","description":"German label."}},"required":["en"]},"AddressInputAttributesResponse":{"type":"object","description":"Attributes and validation metadata for an address input.","properties":{"name":{"type":"string","description":"Field name.","minLength":1,"maxLength":50},"type":{"type":"string","description":"Field type.","enum":["text","number","hidden"],"maxLength":10},"pattern":{"type":"string","description":"Regex pattern for validation.","maxLength":200},"placeholder":{"type":"string","description":"Placeholder text.","maxLength":50},"required":{"type":"boolean","description":"Whether the input is required."},"value":{"type":"string","description":"Default or fixed value.","maxLength":50}},"required":["name","required","type"]},"Iso20022XPathResponse":{"type":"object","description":"ISO 20022 XPath references for the input.","properties":{"acmt023":{"type":["string","null"],"description":"XPath in acmt.023 message.","maxLength":200,"pattern":"^/Document/.+"},"pacs008":{"type":["string","null"],"description":"XPath in pacs.008 message.","maxLength":200,"pattern":"^/Document/.+"}},"required":["acmt023","pacs008"]},"ErrorApiResponse":{"type":"object","description":"Standard structured rejection body. Returned for all non-2xx responses produced by the Nexus authentication layer or the application. Gateway level errors (405, 409, 413, 429, 502, 503, 504) do NOT carry this body.\n\n#### Validation rules\n\n- All four fields are required and never `null`.\n- `statusCode`: always `RJCT`.\n- `reasonCode`: 5 characters matching `^[A-Z]{2}[0-9]{3}$`; family prefix `TE` (technical), `AE` (authentication/authorisation, enforced at authentication) or `BE` (business); one of the values enumerated in the `reasonCode` schema.\n- `name`: UPPER_SNAKE_CASE, 1–50 characters; the name paired with `reasonCode` (e.g. `TE001` ↔ `INVALID_REQUEST`).\n- `description`: 1–500 characters; MUST NOT contain PII.\n- Gateway-level errors (405, 409, 413, 429, 502, 503, 504) do not carry this body.","properties":{"statusCode":{"type":"string","description":"Business-level status code. Always RJCT (Rejected) — the structured error body is only returned for rejection cases. Successful responses use HTTP status alone (200 OK for sync, 202 Accepted for async ingress) with no structured statusCode body.","enum":["RJCT"],"maxLength":4,"minLength":4},"reasonCode":{"type":"string","description":"Categorised reason code. Three families: TE (Technical Error, e.g. TE001/TE002/TE099), AE (Authentication / Authorization Error, AE001–AE006, enforced at authentication), BE (Business Error, BE001–BE031).","enum":["TE001","TE002","TE099","AE001","AE002","AE003","AE004","AE005","AE006","BE001","BE002","BE007","BE008","BE009","BE010","BE011","BE012","BE013","BE014","BE015","BE016","BE017","BE018","BE019","BE020","BE021","BE030","BE031"],"maxLength":5,"pattern":"^[A-Z]{2}[0-9]{3}$","minLength":5},"name":{"type":"string","description":"Machine-readable error name paired with the reason code.","maxLength":50,"pattern":"^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)*$","minLength":1},"description":{"type":"string","description":"Human-readable error description. MUST NOT contain PII.","maxLength":500,"minLength":1}},"required":["description","name","reasonCode","statusCode"]}}},"paths":{"/v1/countries/{countryCode}/address-types-and-inputs":{"get":{"tags":["Address Types"],"summary":"Gets all the address types AND inputs for a specified Country","description":"Returns all address types AND their associated inputs for a specified country.\n\n---\n\n#### Response validation rules\n\n**200 OK** — the body MUST conform to the response schema below. Response objects are open: additional properties may be introduced in later minor versions, and clients MUST ignore properties they do not recognise.\n\nThe body is a top-level JSON array (no envelope); it may be empty unless stated otherwise.\n\n| Field | Type | Presence | Nullable | Constraints |\n|---|---|---|---|---|\n| `[].addressTypeId` | string | Required | N | pattern `^[A-Z]+$`; min length 1; max length 20 |\n| `[].countries` | array | Required | N | each item: pattern `^[A-Z]{2}$`, length 2 |\n| `[].addressTypeCode` | string | Required | N | min length 1; max length 10 |\n| `[].clearingSystemId` | string | Conditional — present when `addressTypeCode` is `ACCT` or `IBAN` | Y | max length 12 |\n| `[].proxyDirectoryId` | string | Conditional — present when `addressTypeCode` is a proxy type (`MBNO`, `EMAL`, `NIDN`) | Y | max length 20 |\n| `[].displayOrder` | integer | Required | N | format `int32`; ≥ 1 |\n| `[].inputs` | array | Required | N | ≥ 1 item(s) |\n| `[].inputs[].addressInputId` | string | Required | N | min length 1; max length 20 |\n| `[].inputs[].label` | object | Conditional — present for visible inputs; absent for `hidden` inputs | Y | — |\n| `[].inputs[].label.addressTypeCode` | string | Required | N | min length 1; max length 10 |\n| `[].inputs[].label.title` | object | Required | N | — |\n| `[].inputs[].label.title.en` | string | Required | N | min length 1; max length 200 |\n| `[].inputs[].label.title.de` | string | Optional | N | — |\n| `[].inputs[].attributes` | object | Required | N | — |\n| `[].inputs[].attributes.name` | string | Required | N | min length 1; max length 50 |\n| `[].inputs[].attributes.type` | string | Required | N | one of `text`, `number`, `hidden`; max length 10 |\n| `[].inputs[].attributes.pattern` | string | Conditional — absent when `type` = `hidden` | N | max length 200 |\n| `[].inputs[].attributes.placeholder` | string | Conditional — absent when `type` = `hidden` | N | max length 50 |\n| `[].inputs[].attributes.required` | boolean | Required | N | — |\n| `[].inputs[].attributes.value` | string | Conditional — present only when `type` = `hidden` | N | max length 50 |\n| `[].inputs[].iso20022XPath` | object | Required | N | — |\n| `[].inputs[].iso20022XPath.acmt023` | string | Required | Y | pattern `^/Document/.+`; max length 200 |\n| `[].inputs[].iso20022XPath.pacs008` | string | Required | Y | pattern `^/Document/.+`; max length 200 |\n\n**Cross-field rules**\n\n- `addressTypeId` is unique within the country; `inputs[].addressInputId` is unique within its address type.\n- `clearingSystemId` is populated for account types (`ACCT`, `IBAN`) and `null` for proxy types; `proxyDirectoryId` is populated for proxy types (`MBNO`, `EMAL`, `NIDN`) and `null` for account types.\n- For inputs with `attributes.type` = `hidden`: `label`, `attributes.pattern` and `attributes.placeholder` are absent and `attributes.value` is present.\n- `attributes.pattern`, when present, is a valid regular expression.\n- `iso20022XPath.acmt023` / `iso20022XPath.pacs008` are `null` when the input is not mapped to that message.\n\n**Response signature** — every 200 and 304 response carries `Signature-Input` and `Signature` (plus `Content-Digest` on 200) per the Nexus HTTP Message Signature Profile v1, signed by the responding server. The client MUST verify the response signature before using the response and MUST discard a response that fails verification.\n\n**Error responses (4xx/5xx with a body)** — the body MUST conform to `ErrorApiResponse`: `statusCode` = `RJCT`; `reasonCode` matches `^[A-Z]{2}[0-9]{3}$`; `name` is UPPER_SNAKE_CASE (≤ 50); `description` ≤ 500 characters and MUST NOT contain PII. `reasonCode` values for this operation: `TE001`, `BE001`, `BE002`, `TE099`, `AE001`, `AE002`, `AE003`, `AE005`, `AE006`, `AE004`. Gateway errors (405, 429, 502, 503, 504) carry no body.","operationId":"listAddressTypesWithInputs","parameters":[{"name":"Accept","in":"header","description":"*/*","required":true,"schema":{"type":"string","default":"*/*"}},{"name":"countryCode","in":"path","description":"ISO 3166-1 alpha-2 uppercase country code used to scope the lookup. Must match the Sender’s selected destination country.","required":true,"schema":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Z]{2}$"}},{"name":"If-None-Match","in":"header","description":"Optional. ETag value from a previous response for conditional GET. If it matches the current entity tag, the server returns 304 Not Modified with no body.","required":false,"schema":{"type":"string"}},{"$ref":"#/components/parameters/SignatureInputBodyless"},{"$ref":"#/components/parameters/Signature"}],"responses":{"200":{"description":"Address types and inputs for the specified country.","headers":{"ETag":{"description":"Entity tag for cache validation","style":"simple","schema":{"type":"string"}},"Cache-Control":{"description":"Caching guidance for this reference-data resource. Nexus invalidates the underlying cache immediately when the underlying configuration changes; responses may otherwise be cached for up to 300 seconds.","schema":{"type":"string"}},"Signature-Input":{"$ref":"#/components/headers/ResponseSignatureInput"},"Signature":{"$ref":"#/components/headers/ResponseSignature"},"Content-Digest":{"$ref":"#/components/headers/ResponseContentDigest"}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AddressTypeWithInputsResponse"}}}}},"304":{"description":"Not Modified. The resource has not changed since the last request.","headers":{"ETag":{"description":"Entity tag for cache validation","style":"simple","schema":{"type":"string"}},"Signature-Input":{"$ref":"#/components/headers/ResponseSignatureInput"},"Signature":{"$ref":"#/components/headers/ResponseSignature"}}},"400":{"description":"Invalid Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"401":{"description":"Authentication Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"403":{"description":"Authorization Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"404":{"description":"Resource Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"405":{"description":"Method Not Allowed. The HTTP method is not supported for this endpoint. Use the correct HTTP method.","headers":{"Allow":{"description":"Permitted HTTP methods for this endpoint","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests. Rate limit exceeded. The Retry-After header indicates when to retry. Back off and retry after the indicated duration.","headers":{"Retry-After":{"description":"Duration after which the caller may retry","schema":{"type":"integer","minimum":0}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApiResponse"}}}},"502":{"description":"Bad Gateway. The gateway received an invalid response from the upstream service. Retry with exponential backoff. If persistent, escalate."},"503":{"description":"Service Unavailable. The upstream service is temporarily unavailable, for example during rolling deployment. Retry with exponential backoff."},"504":{"description":"Gateway Timeout. The upstream service did not respond within the gateway's timeout window. Retry with exponential backoff."}}}}}}
```