Address
The Address resource represents physical addresses for a profile. Once an address is created, it can be added to a profile.
Address ID
User profile ID
Country code (ISO 3166-2 Country Code)
Address line: street, house, apartment
Postal / zip code
City name
State code | Required if country is US, CA, BR, AU
User occupation - any value permitted
Occupation type - always FREE_FORM
{"id": 10000001,"profile": {{profile ID}},"details": {"country" : "US","state": "AZ","city": "Phoenix","postCode": "10025","firstLine": "50 Sunflower Ave","occupations": [{"code": "Software Engineer","format": "FREE_FORM"}]}}
POST /v1/addresses
Adds address info to user profile. List of required fields are different for different countries.
For updating personal profiles, consider using the personal profile update endpoint instead. It allows to submit the address information alongside the other profile data.
State field is required for US, CA, BR and AU addresses.
Occupations is required for CA, IN, JP and within the US for the states AZ and NM. If you serve any of these jurisdictions we recommend submitting occupation for all customers for simplicity, however if this is an issue we can discuss alternative solutions.
User profile ID
Country code (ISO 3166-2 Country Code)
Address line: street, house, apartment
Zip code
City name
State code | Required if country is US, CA, BR, AU
User occupation - any value permitted
Occupation type - always FREE_FORM
Returns an address object
curl -X POST https://api.sandbox.transferwise.tech/v1/addresses \-H 'Authorization: Bearer <your api token>' \-H 'Content-Type: application/json' \-d '{"profile": {{profile ID}},"details": {"country" : "US","state": "AZ","city": "Phoenix","postCode": "10025","firstLine": "50 Sunflower Ave","occupations": [{"code": "Software Engineer","format": "FREE_FORM"}]}}'
curl -X GET https://api.sandbox.transferwise.tech/v1/addresses/{{addressId}} \-H 'Authorization: Bearer <your api token>'
GET /v1/addresses?profile={{profileId}}
List of addresses belonging to user profile.
Returns an array of address objects.
curl -X GET https://api.sandbox.transferwise.tech/v1/addresses?profile={{profileId}} \-H 'Authorization: Bearer <your api token>'
GET /v1/address-requirements
POST /v1/address-requirements
GET and POST address-requirements endpoints help you to figure out which fields are required to create a valid address for different countries. You could even build a dynamic user interface on top of these endpoints. This is a step-by-step guide on how these endpoints work.
- Call
GET /v1/address-requirementsto get list of fields you need to fill with values in "details" section for creating a valid address. Response contains 4 required top level fields:
- country (select field with list of values)
- city (text field)
- postCode (text field)
- firstLine (text field)
Analyze the list of fields. Because
refreshRequirementsOnChangefor field 'country' is marked astruethen this indicates that there are additional fields required depending on the selected value.Call
POST /v1/address-requirementswith selected country value to expose sub-fields.
For example posting{"details": {"country" : "US"}}will also add "state" to list of fields.
But posting{"details": {"country" : "GB"}}will not.If you choose "US" as country you will notice that "state" field also has
refreshRequirementsOnChange=true. This means you would need to make another POST call to/v1/address-requirementswith a specific state value.
For example posting{"details": { "country" : "US", "state": "AZ" }}will also add "occupation" to list of fields.
But posting{"details": { "country" : "US", "state": "AL" }}will not.So once you get to the point where you have provided values for all fields which have refreshRequirementsOnChange=true then you have complete set of fields to compose a valid request to create an address object.
"address"
Field description
Key is name of the field you should include in the JSON
Display type of field (e.g. text, select, etc)
Tells you whether you should call POST address-requirements once the field value is set to discover required lower level fields
Indicates if the field is mandatory or not
Display format pattern
Example value to help customers understand what to input
Min valid length of field value
Max valid length of field value
Regexp validation pattern
Validator URL and parameter name you should use when submitting the value for validation
List of allowed value's key
List of allowed value's name
curl -X GET https://api.sandbox.transferwise.tech/v1/address-requirements \-H 'Authorization: Bearer <your api token>'curl -X POST https://api.sandbox.transferwise.tech/v1/address-requirements \-H 'Authorization: Bearer <your api token>' \-d '{"profile" : {{profile ID}},"details": {"country" : "US","state": "AZ","city": "Phoenix","postCode": "10025","firstLine": "50 Sunflower Ave","occupations": [{"code": "Software Engineer","format": "FREE_FORM"}]}}'
[{"type": "address","fields": [{"name": "Country","group": [{"key": "country","type": "select","refreshRequirementsOnChange": true,"required": true,"displayFormat": null,"example": "Germany","minLength": null,"maxLength": null,"validationRegexp": null,"validationAsync": null,"valuesAllowed": [{"key": "AX","name": "Åland Islands"},...{"key": "ZM","name": "Zambia"}]}]},{"name": "City","group": [{"key": "city","type": "text","refreshRequirementsOnChange": false,"required": true,"displayFormat": null,"example": "London","minLength": null,"maxLength": null,"validationRegexp": null,"validationAsync": null,"valuesAllowed": null}]},{"name": "Postal code","group": [{"key": "postCode","type": "text","refreshRequirementsOnChange": false,"required": true,"displayFormat": null,"example": "10025","minLength": null,"maxLength": null,"validationRegexp": null,"validationAsync": null,"valuesAllowed": null}]}...]}]