Skip to content
Last updated

Address Requirements

Address requirements vary by country. Use the address requirements endpoints to dynamically discover which fields are needed before creating an address. You can use this to build a dynamic UI that adapts to each country's requirements.

How it works

Step 1: Get initial requirements and render fields

Call GET /v1/address-requirements to retrieve the initial list of required fields, then render them in your UI.

curl -i -X GET \
  https://api.wise.com/v1/address-requirements \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

The response contains four base fields:

  • country (select field with list of values)
  • city (text field)
  • postCode (text field)
  • firstLine (text field)
Response
application/json
[
  {
    "type": "address",
    "fields": [
      { … }
    ]
  }
]

Step 2: Check for dynamic fields

When the user selects a value, check if that field has refreshRequirementsOnChange: true. The country field has this set to true, meaning additional fields may be required depending on the selected country.

Step 3: Get context-specific requirements and update UI

Call POST /v1/address-requirements with the current form state to discover additional fields, then update your UI with any new fields returned.

curl -i -X POST \
  https://api.wise.com/v1/address-requirements \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "details": {
      "country": "US"
    }
  }'

For example, posting {"details": {"country": "US"}} adds state to the list of required fields. Posting {"details": {"country": "GB"}} does not add any additional fields.

Step 4: Repeat until complete

Continue calling POST with updated values whenever a field with refreshRequirementsOnChange: true changes.

For example, posting {"details": {"country": "CA"}} adds occupations to the list of fields. Posting {"details": {"country": "US", "state": "AL"}} does not.

Once all dynamic fields are resolved, you have the complete set of fields needed to create a valid address.

For full endpoint details, see the Address API Reference.