# Get Address Requirements (with context)

Returns the list of fields required to create a valid address, based on the provided context.
Use this endpoint to dynamically discover additional required fields based on selected values. For example:
- Posting `{"details": {"country": "US"}}` will add "state" to the list of fields.
- Posting `{"details": {"country": "CA"}}` will add "occupations" to the list of fields.

Continue calling this endpoint with field values until all fields with `refreshRequirementsOnChange: true` have been populated.
For a step-by-step walkthrough, see the [Address Requirements guide](/guides/developer/api-guides/address-requirements).

Endpoint: POST /v1/address-requirements
Security: UserToken, PersonalToken

## Security:

  - `UserToken` (unknown)
    http bearer JWT

  - `PersonalToken` (unknown)
    http bearer JWT

## Header parameters:

  - `X-External-Correlation-Id` (string)
    Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. [Learn more](/guides/developer/headers/correlation-id).

## Request fields (application/json):

  - `profile` (integer)
    User profile ID.
    Example: 12345678

  - `details` (object, required)
    Address details to provide context for requirements lookup. Additional fields beyond those listed are accepted.

  - `details.country` (string, required)
    Country code (ISO 3166-2 Country Code).
    Example: US

  - `details.state` (string)
    State code. Provide to discover state-dependent fields.
    Example: AZ

## Response 200:

  - `200` (unknown)
    OK - Successfully retrieved address requirements.

## Response 200 fields (application/json):

  - `type` (string)
    Always "address".
    Example: address

  - `fields` (array)
    List of fields required for the address.

  - `fields.name` (string)
    Display name of the field.
    Example: Country

  - `fields.group` (array)

  - `fields.group.key` (string)
    Key name to include in the JSON request.
    Example: country

  - `fields.group.type` (string)
    Display type of field.
    Enum: "text", "select"

  - `fields.group.refreshRequirementsOnChange` (boolean)
    If true, call POST address-requirements when this field value changes to discover additional required fields.
    Example: true

  - `fields.group.required` (boolean)
    Indicates if the field is mandatory.
    Example: true

  - `fields.group.displayFormat` (string | null)
    Display format pattern.
    Example: null

  - `fields.group.example` (string)
    Example value to help users understand what to input.
    Example: Germany

  - `fields.group.minLength` (integer | null)
    Minimum valid length of field value.
    Example: null

  - `fields.group.maxLength` (integer | null)
    Maximum valid length of field value.
    Example: null

  - `fields.group.validationRegexp` (string | null)
    Regexp validation pattern.
    Example: null

  - `fields.group.validationAsync` (string | null)
    Deprecated. This validation will instead be performed when submitting the request.
    Example: null

  - `fields.group.valuesAllowed` (array)
    List of allowed values (for select fields).
    Example: [{"key":"US","name":"United States"},{"key":"GB","name":"United Kingdom"}]

  - `fields.group.valuesAllowed.key` (string)
    Value key to use in the request.

  - `fields.group.valuesAllowed.name` (string)
    Display name for the value.

## Response 200 headers (application/json):

  - `X-External-Correlation-Id` (string)
    Echoed back when `X-External-Correlation-Id` was included in the request. [Learn more](/guides/developer/headers/correlation-id).
    Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

  - `x-trace-id` (string)
    Unique trace identifier assigned by Wise. Useful when contacting support about a specific request.
    Example: fba501b6d453b96789f52338f019341f

## Response 429:

  - `429` (unknown)
    Rate limit exceeded. Retry after the number of seconds specified in the `Retry-After` header.

## Response 429 headers (application/json):

  - `Retry-After` (integer)
    Number of seconds to wait before retrying the request.
    Example: 5

  - `X-Rate-Limited-By` (string)
    Identifies the rate limiter that triggered the 429 response.
    Example: wise-public-api

  - `X-External-Correlation-Id` (string)
    Echoed back when `X-External-Correlation-Id` was included in the request. [Learn more](/guides/developer/headers/correlation-id).
    Example: f47ac10b-58cc-4372-a567-0e02b2c3d479

  - `x-trace-id` (string)
    Unique trace identifier assigned by Wise. Useful when contacting support about a specific request.
    Example: fba501b6d453b96789f52338f019341f