Profile

Profiles are connected to a User account and are either personal or business. The requests described here refer to a {{profileId}} or "profile id" - this value can be the business profile id, or the personal profile id.

Endpoints
POST/v1/profiles
POST/v2/profiles/business-profile
PUT/v1/profiles
GET/v1/profiles/{{profileId}}
GET/v2/profiles
POST/v1/profiles/{{profileId}}/verification-documents
POST/v1/profiles/{{profileId}}/directors
GET/v1/profiles/{{profileId}}/directors
PUT/v1/profiles/{{profileId}}/directors
POST/v1/profiles/{{profileId}}/ubos
GET/v1/profiles/{{profileId}}/ubos
PUT/v1/profiles/{{profileId}}/ubos
DELETE/v3/profiles/{{profileId}}/trusted-verification
POST/v1/profiles/{{profileId}}/update-window
DELETE/v1/profiles/{{profileId}}/update-window
GET/v1/profiles/{{profileId}}/extension-requirements
POST/v1/profiles/{{profileId}}/extension-requirements
Fields
idinteger

profileId

typetext

"personal"

details.firstNametext

First name

details.lastNametext

Last name

details.dateOfBirthyyyy-mm-dd

Date of birth

details.phoneNumbertext

Phone number

details.avatartext

Link to person avatar image

details.occupation (Deprecated)text

Person occupation

details.occupationsarray (can be null or empty)

Array of occupations, currently one FREE_FORM occupation is supported, required as described above.

details.occupations[n].codetext

User occupation, any value permitted.

details.occupations[n].formattext

Occupation type - always FREE_FORM

details.primaryAddressinteger

Address object id

details.firstNameInKanatext (katakana)

First name in Katakana (required for from JPY personal transfers)

details.lastNameInKanatext (katakana)

Last name in Katakana (required for from JPY personal transfers)

Personal Profile Object
{
"id": 30000001,
"type": "personal",
"details": {
"firstName": "Oliver",
"lastName": "Wilson",
"dateOfBirth": "1977-07-01",
"phoneNumber": "+3725064992",
"avatar": "",
"occupation": "",
"occupations": null,
"primaryAddress": null,
"firstNameInKana": null,
"lastNameInKana": null
}
}
Business Profile Object
{
"id": 30000002,
"type": "business",
"details": {
"name": "ABC Logistics Ltd",
"registrationNumber": "12144939",
"acn": null,
"abn": null,
"arbn": null,
"companyType": "LIMITED",
"companyRole": "OWNER",
"descriptionOfBusiness": "Information and communication",
"webpage": "https://abc-logistics.com",
"primaryAddress": 4000001,
"businessCategory": "CONSULTING_IT_BUSINESS_SERVICES",
"businessSubCategory": "DESIGN"
}
}

POST /v1/profiles

Create personal user profile.

One person cannot have multiple active duplicate user profiles, creating multiple profiles with the same details will fail. When this happens, you should show an error message to the user informing them that they may have an existing Wise account. The customer should then be allowed to link to an existing Wise account.

If a customer you are creating a profile for has first or last names that exceed 30 characters (e.g. they have many middle names) then you should truncate the names at length 30 characters and submit that value.

Request Fields
typetext

"personal"

details.firstNametext (max 30 chars)

First name (including middle names)

details.lastNametext (max 30 chars)

Last name

details.dateOfBirthyyyy-mm-dd

Date of birth

details.phoneNumbertext

Phone number

details.firstNameInKanatext (katakana)

First name in Katakana (required for from JPY personal transfers)

details.lastNameInKanatext (katakana)

Last name in Katakana (required for from JPY personal transfers)

Example Request
curl -X POST https://api.sandbox.transferwise.tech/v1/profiles \
-H 'Authorization: Bearer <your api token>' \
-H 'Content-Type: application/json' \
-d '{
"type": "personal",
"details": {
"firstName": "Oliver",
"lastName": "Wilson",
"dateOfBirth": "1977-07-01",
"phoneNumber": "+3725064992",
"firstNameInKana": null,
"lastNameInKana": null
}
}'

POST /v2/profiles/business-profile

Creating a personal profile is a prerequisite for setting up a business profile. It is not possible to create a business profile without first creating a personal profile.

One person cannot have multiple active duplicate business profiles. Creating multiple profiles with the same details may fail. When this happens, you should show an error message to the user informing them that they may have an existing Wise account. The customer should then be allowed to link to an existing Wise account.

Title
businessNametext

Business name

businessNameInKatakanatext (Katakana)

Business name in Katakana (only for Japanese businesses)

businessFreeFormDescriptiontext

Business free form description. *Required if companyType is OTHER. If this is not provided for an OTHER companyType, the profile should not be allowed to create a transfer. For the rest of the companyType(s), it is highly recommended to always provide the business' description, to avoid payment issues such as suspensions. Wise will send a request for information (RFI) if this detail is not provided.

registrationNumbertext

Business registration number

acntext

Australian Company Number (only for Australian businesses)

abntext

Australian Business Number (only for Australian businesses)

arbntext

Australian Registered Body Number (only for Australian businesses)

companyTypetext

Company legal form. Allowed values:

  • LIMITED
  • PARTNERSHIP
  • SOLE_TRADER
  • LIMITED_BY_GUARANTEE
  • LIMITED_LIABILITY_COMPANY
  • FOR_PROFIT_CORPORATION
  • NON_PROFIT_CORPORATION
  • LIMITED_PARTNERSHIP
  • LIMITED_LIABILITY_PARTNERSHIP
  • GENERAL_PARTNERSHIP
  • SOLE_PROPRIETORSHIP
  • PRIVATE_LIMITED_COMPANY
  • PUBLIC_LIMITED_COMPANY
  • TRUST
  • OTHER
companyRoletext

Role of person. Allowed Values:

  • OWNER
  • DIRECTOR
  • OTHER
address.addressFirstLinetext

First line of address

address.citytext

City

address.countryIso2Codetext

2 letter country code.

address.countryIso3Codetext

3 Letter country code. Must be lowercase

address.postCodetext

Postal code

address.stateCodetext

State code

actorEmailtext

Email of the actor

firstLevelCategorytext

Category of the business

secondLevelCategorytext

Secondary category of the business

operationalAddressesarray

List of operational addresses

operationalAddresses[0].addressFirstLinetext

First line of address

operationalAddresses[0].citytext

City

operationalAddresses[0].countryIso2Codetext

2 letter country code

operationalAddresses[0].countryIso3Codetext

3 Letter country code. Must be lowercase

operationalAddresses[0].postCodetext

Postal code

operationalAddresses[0].stateCodetext

State code

webpage (conditional)text

Business webpage. *Required if companyType is OTHER. If this is not provided for an OTHER companyType, the profile should not be allowed to create a transfer. For the rest of the companyTypes, it is highly recommended to always provide the business' website,to avoid payment issues such as suspensions. Wise will send a request for information (RFI) if this detail is not provided.

Business Category

Ensure when submitting a business profile that you submit a category and associated sub-category from the list below. You should map from the information you have about the business to one of our categories and sub-categories. If this is problematic please get in touch with us to discuss alternate solutions.

The categories and their sub-categories are as follows:

  • CHARITY_NON_PROFIT
    • CHARITY_ALL_ACTIVITIES
  • CONSULTING_IT_BUSINESS_SERVICES
    • ADVERTISING_AND_MARKETING
    • ARCHITECTURE
    • COMPANY_ESTABLISHMENT_FORMATION_SERVICES
    • DESIGN
    • FINANCIAL_CONSULTING_ACCOUNTING_TAXATION_AUDITING
    • IT_DEVELOPMENT
    • IT_HOSTING_SERVICES
    • IT_CONSULTING_AND_SERVICES
    • LEGAL_SERVICES
    • MANAGEMENT_CONSULTING
    • SCIENTIFIC_AND_TECHNICAL_CONSULTING
    • SOFTWARE_AS_A_SERVICE
    • TRANSLATION_AND_LANGUAGE_SERVICES
    • CONSULTING_OTHER
    • SERVICES_OTHER
    • FREELANCE_PLATFORMS
    • RECRUITMENT_SERVICES
    • MAINTENANCE_SERVICES
    • FREELANCE_PLATFORMS
  • DESIGN_MARKETING_COMMUNICATIONS
    • ADVERTISING_AND_MARKETING
    • ARCHITECTURE
    • AUDIO_AND_VIDEO
    • DESIGN
    • PHOTOGRAPHY
    • PRINT_AND_ONLINE_MEDIA
    • TELECOMMUNICATIONS_SERVICES
    • TRANSLATION_AND_LANGUAGE_SERVICES
  • MEDIA_COMMUNICATION_ENTERTAINMENT
    • ADULT_CONTENT
    • AUDIO_AND_VIDEO
    • FINE_ARTS
    • ARTS_OTHER
    • EVENTS_AND_ENTERTAINMENT
    • GAMBLING_BETTING_AND_ONLINE_GAMING
    • NEWSPAPERS_MAGAZINES_AND_BOOKS
    • PERFORMING_ARTS
    • PHOTOGRAPHY
    • TELECOMMUNICATIONS_SERVICES
    • VIDEO_GAMING
  • EDUCATION_LEARNING
    • SCHOOLS_AND_UNIVERSITIES,
    • TEACHING_AND_TUTORING
    • ONLINE_LEARNING
  • FINANCIAL_SERVICES_PRODUCTS_HOLDING_COMPANIES
    • CROWDFUNDING
    • CRYPTOCURRENCY_FINANCIAL_SERVICES
    • FINANCIAL_CONSULTING_ACCOUNTING_TAXATION_AUDITING
    • HOLDING_COMPANIES
    • INSURANCE
    • INVESTMENTS
    • MONEY_SERVICE_BUSINESSES
    • FINANCIAL_SERVICES_OTHER
  • FOOD_BEVERAGES_TOBACCO
    • ALCOHOL
    • FOOD_MANUFACTURING_RETAIL
    • RESTAURANTS_AND_CATERING
    • SOFT_DRINKS
    • TOBACCO
    • VITAMINS_AND_DIETARY_SUPPLEMENTS
  • HEALTH_PHARMACEUTICALS_PERSONAL_CARE
    • HEALTH_AND_BEAUTY_PRODUCTS_AND_SERVICES
    • DENTAL_SERVICES
    • DOCTORS_AND_MEDICAL_SERVICES
    • ELDERLY_OR_OTHER_CARE_HOME
    • FITNESS_SPORTS_SERVICES
    • MEDICAL_EQUIPMENT
    • NURSING_AND_OTHER_CARE_SERVICES
    • PHARMACEUTICALS
    • PHARMACY
    • VITAMINS_AND_DIETARY_SUPPLEMENTS
  • PUBLIC_GOVERNMENT_SERVICES
    • PUBLIC_ALL_SERVICES
    • MAINTENANCE_SERVICES
    • GOVERNMENT_SERVICES
    • TELECOMMUNICATIONS_SERVICES
    • UTILITY_SERVICES
  • REAL_ESTATE_CONSTRUCTION
    • ARCHITECTURE
    • CONSTRUCTION
    • REAL_ESTATE_DEVELOPMENT
    • REAL_ESTATE_SALE_PURCHASE_AND_MANAGEMENT
  • RETAIL_WHOLESALE_MANUFACTURING
    • AGRICULTURE_SEEDS_PLANTS
    • FINE_ARTS
    • ARTS_OTHER
    • AUTOMOTIVE_SALES_SPARE_PARTS_TRADE
    • AUTOMOTIVE_MANUFACTURING
    • CHEMICALS
    • CLOTHING
    • ELECTRICAL_PRODUCTS
    • FIREARMS_WEAPONS_AND_MILITARY_GOODS_SERVICES
    • HOME_ACCESSORIES_FURNITURE
    • FINE_JEWELLERY_WATCHES
    • FASHION_JEWELLERY
    • HEALTH_AND_BEAUTY_PRODUCTS_AND_SERVICES
    • LEGAL_HIGHS_AND_RELATED_ACCESSORIES
    • MACHINERY
    • PETS
    • PRECIOUS_STONES_DIAMONDS_AND_METALS
    • SPORTING_EQUIPMENT
    • MANUFACTURING_OTHER
    • RETAIL_WHOLESALE_MARKETPLACE_AUCTION
    • RETAIL_WHOLESALE_OTHER
    • TOYS_AND_GAMES
  • TRAVEL_TRANSPORT_TOUR_AGENCIES
    • ACCOMMODATION_HOTELS
    • PASSENGER_TRANSPORT
    • FREIGHT_TRANSPORT
    • RIDESHARING_TRANSPORT_SHARING_SERVICES
    • TRANSPORT
    • TRAVEL_AGENCIES
    • TOUR_OPERATORS
    • TRAVEL_OR_TOUR_ACTIVITIES_OTHER
  • OTHER
    • OTHER_NOT_LISTED_ABOVE
Example Request
curl -X POST https://api.sandbox.transferwise.tech/v2/profiles/business-profile \
-H 'Authorization: Bearer <your api token>' \
-H 'Content-Type: application/json' \
-d '{
"businessName": "ABC Logistics Ltd",
"businessNameInKatakana": null,
"businessFreeFormDescription": "Biz free form desc",
"registrationNumber": "12144939",
"acn": null,
"abn": null,
"arbn": null,
"companyType": "LIMITED",
"companyRole": "OWNER",
"address": {
"addressFirstLine": "1 A road",
"city": "London",
"countryIso2Code": "gb",
"countryIso3Code": "gbr",
"postCode": "11111"
},
"actorEmail": "biz-acct@abcl.com",
"firstLevelCategory": "CONSULTING_IT_BUSINESS_SERVICES",
"secondLevelCategory": "DESIGN",
"operationalAddresses": [
{
"addressFirstLine": "1 A road",
"city": "London",
"countryIso2Code": "gb",
"countryIso3Code": "gbr",
"postCode": "11111"
}
],
"webpage": "https://abc-logistics.com"
}'

PUT /v1/profiles

Update user profile information.

Request and response is same as described in Create (Personal) and Create (Business)

If user profile has been verified then there are restrictions on what information is allowed to change, where permitted, use the update window functionality to submit updated data.
Example Request
curl -X PUT https://api.sandbox.transferwise.tech/v1/profiles \
-H 'Authorization: Bearer <your api token>' \
-H 'Content-Type: application/json' \
-d '{
"id": <your personal profile id>
"type": "personal",
"details": {
"firstName": "Oliver",
"lastName": "Wilson",
"dateOfBirth": "1977-07-01",
"phoneNumber": "+3725064992",
"firstNameInKana": null,
"lastNameInKana": null
}
}'

GET /v1/profiles/{{profileId}}

Get profile info by id.

Example Request
curl -X GET https://api.sandbox.transferwise.tech/v2/profiles \
-H 'Authorization: Bearer <your api token>'

GET /v2/profiles

List of all profiles belonging to user.

Response

An array of profile objects will be returned. Note that there might be more than one business profile returned in the response.

Example Request
curl -X GET https://api.sandbox.transferwise.tech/v2/profiles \
-H 'Authorization: Bearer <your api token>'

POST /v1/profiles/{{profileId}}/verification-documents

Add identification document details to user profile. Applicable to personal profiles (not business) only.
Returns empty result if successful.

When sending a social security number (SSN) only type and uniqueIdentifier (only 9 digits no letters or symbols) are required.

Request Fields
firstNametext

Person first name in document.

lastNametext

Person last name in document.

type (conditional)text

Document type. Allowed Values:

  • DRIVERS_LICENCE
  • IDENTITY_CARD
  • GREEN_CARD
  • MY_NUMBER
  • PASSPORT
  • SSN
  • EMIRATES_EMPLOYER
  • EMIRATES_PLACE_OF_BIRTH
  • CPF_CNPJ
  • FINANCIAL_CAPACITY_BR
  • OTHER
uniqueIdentifier (required)text

Document number or value. Only digits when SSN or FINANCIAL_CAPACITY_BR

issueDateyyyy-mm-dd

Document issue date.

issuerCountrytext

Issued by country code. For example "US".

issuerStatetext

Issued by state code. For example "NY".

expiryDateyyyy-mm-dd

Document expiry date.

nationalitytext

2 characters ISO country code.

employerNametext

The name of the employer. Type must be EMIRATES_EMPLOYER.

employerCitytext

The city of the employer. Type must be EMIRATES_EMPLOYER.

employerCountrytext

2 characters ISO country code. Type must be EMIRATES_EMPLOYER.

birthCitytext

The city of birth of the customer. Type must be EMIRATES_PLACE_OF_BIRTH

birthCountrytext

2 characters ISO country code. Type must be EMIRATES_PLACE_OF_BIRTH

Example Request
curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/verification-documents \
-H 'Authorization: Bearer <your api token>' \
-H 'Content-Type: application/json' \
-d '{
"firstName": "Oliver",
"lastName": "Wilson",
"type": "IDENTITY_CARD",
"uniqueIdentifier": "AA299822313",
"issueDate": "2017-12-31",
"issuerCountry": "EE",
"issuerState": "",
"expiryDate": "2027-12-31"
}'
Request Payload - CPF or CNPJ
{
"type": "CPF_CNPJ",
"uniqueIdentifier": "938.936.652-69"
}
Request Payload - Financial Capacity Brazil
{
"type": "FINANCIAL_CAPACITY_BR",
"uniqueIdentifier": "150000.00"
}
Example Response
{
"errorMessage": null,
"success": true
}

POST /v1/profiles/{{business-profile-id}}/directors

Adds new directors to the business profile.

Returns the list of all directors associated with the business profile.

Director Object Fields
idinteger

ID of the director. Automatically set.

firstNametext

Director first name

lastNametext

Director last name

dateOfBirthyyyy-mm-dd

Date of birth

countryOfResidenceIso3Codetext

3 character country code

Example Request
curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{{business-profile-id}}/directors \
-H "Authorization: Bearer <your api token>" \
-H "Content-Type: application/json" \
-d '[
{
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "1982-05-20",
"countryOfResidenceIso3Code": "usa"
},
{
"firstName": "Jane",
"lastName": "Doe",
"dateOfBirth": "1981-12-07",
"countryOfResidenceIso3Code": "usa"
}
]'

GET /v1/profiles/{{business-profile-id}}/directors

Returns the list of director objects associated with the business profile.

Example Request
curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{{business-profile-id}}/directors \
-H 'Authorization: Bearer <your api token>'
Example Response
[
{
"id": 10,
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "1982-05-20",
"countryOfResidenceIso3Code": "usa"
},
{
"id": 11,
"firstName": "Jane",
"lastName": "Doe",
"dateOfBirth": "1981-12-07",
"countryOfResidenceIso3Code": "usa"
}
]

PUT /v1/profiles/{{business-profile-id}}/directors

Overrides directors in the business profile. Returns the list of all directors associated with the business profile.

Example Request
curl -X PUT https://api.sandbox.transferwise.tech/v1/profiles/{{business-profile-id}}/directors \
-H 'Authorization: Bearer <your api token>' \
-H 'Content-Type: application/json' \
-d '[
{
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "1982-05-20",
"countryOfResidenceIso3Code": "usa"
},
{
"firstName": "Jane",
"lastName": "Doe",
"dateOfBirth": "1981-12-07",
"countryOfResidenceIso3Code": "usa"
}
]'
Example Response
[
{
"id": 14,
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "1982-05-20",
"countryOfResidenceIso3Code": "usa"
},
{
"id": 15,
"firstName": "Jane",
"lastName": "Doe",
"dateOfBirth": "1981-12-07",
"countryOfResidenceIso3Code": "usa"
}
]

POST /v1/profiles/{{business-profile-id}}/ubos

Adds new ultimate beneficial owners to the business profile. Returns the list of all ultimate beneficial owners associated with the business profile.

Note that in some cases, we do not require the ownershipPercentage. In these cases, null should be passed as the value.

Ultimate Business Owner Object
nametext

Owner full name

dateOfBirthyyyy-mm-dd

Date of birth

countryOfResidenceIso3Codetext

3 character country code

addressFirstLinetext

First line of address

postCodetext

Address post code

ownershipPercentageinteger

Percentage of ownership

Example Request
curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{{business-profile-id}}/ubos \
-H 'Authorization: Bearer <your api token>' \
-H 'Content-Type: application/json' \
-d '[
{
"name": "John Doe",
"dateOfBirth": "1982-05-20",
"countryOfResidenceIso3Code": "usa",
"addressFirstLine": "123 Fake St",
"postCode": "FK 12345",
"ownershipPercentage": 30
}
]'
Example Response
[
{
"id": "013ab1c2688d0185b582ee7e0bcb28b2",
"name": "John Doe",
"dateOfBirth": "1982-05-20",
"countryOfResidenceIso3Code": "usa",
"addressFirstLine": "123 Fake St",
"postCode": "FK 12345",
"ownershipPercentage": 30
}
]

GET /v1/profiles/{{business-profile-id}}/ubos

Returns the list of all ultimate beneficial owners associated with the business profile.

Example Request
curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{{business-profile-id}}/ubos \
-H 'Authorization: Bearer <your api token>'
Example Response
[
{
"id": "013ab1c2688d0185b582ee7e0bcb28b2",
"name": "John Doe",
"dateOfBirth": "1982-05-20",
"countryOfResidenceIso3Code": "usa",
"addressFirstLine": "123 Fake St",
"postCode": "FK 12345",
"ownershipPercentage": 30
},
{
"id": "912ce3f31c8b3a10572137e78417caa3",
"name": "Jane Doe",
"dateOfBirth": "1981-12-07",
"countryOfResidenceIso3Code": "usa",
"addressFirstLine": "125 Fake St",
"postCode": "FK 12545",
"ownershipPercentage": 70
}
]

PUT /v1/profiles/{{business-profile-id}}/ubos

Overrides ultimate beneficial owners in the business profile.

Returns the list of all ultimate beneficial owners associated with the business profile.

Example Request
curl -X PUT https://api.sandbox.transferwise.tech/v1/profiles/{{business-profile-id}}/ubos \
-H 'Authorization: Bearer <your api token>' \
-H 'Content-Type: application/json' \
-d '[
{
"name": "John Doe",
"dateOfBirth": "1982-05-20",
"countryOfResidenceIso3Code": "usa",
"addressFirstLine": "123 Fake St",
"postCode": "FK 12345",
"ownershipPercentage": 30
},
{
"name": "Jane Doe",
"dateOfBirth": "1981-12-07",
"countryOfResidenceIso3Code": "usa",
"addressFirstLine": "125 Fake St",
"postCode": "FK 12545",
"ownershipPercentage": 70
}
]'
Example Response
[
{
"id": "ff01cf3f206b40c090a14a1e51163e9e",
"name": "John Doe",
"dateOfBirth": "1982-05-20",
"countryOfResidenceIso3Code": "usa",
"addressFirstLine": "123 Fake St",
"postCode": "FK 12545",
"ownershipPercentage": 30
},
{
"id": "c36b687d28ad44ad8c3864411f5f2612",
"name": "Jane Doe",
"dateOfBirth": "1981-12-07",
"countryOfResidenceIso3Code": "usa",
"addressFirstLine": "125 Fake St",
"postCode": "FK 12545",
"ownershipPercentage": 70
}
]

DELETE /v3/profiles/{{profileId}}/trusted-verification

This endpoint allows partners to remove the verification that was given to the profile through them creating the profile. This does not delete a profile nor archive it, it simply removes the trusted verification from that partner.

Note that this uses a client-credentials-token and not a user access_token for authentication.

Example Request
curl -X DELETE https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/trusted-verification \
-H 'Authorization: Bearer <client-credentials-token>'
Example Response - 204
No Content

POST /v1/profiles/{{profileId}}/update-window

Opens the update window for updating the profile information: details, addresses, directors, owners, others.

Example Request
curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/update-window \
-H 'Authorization: Bearer <your api token>'

DELETE /v1/profiles/{{profileId}}/update-window

Deletes the update window for updating the profile.

Example Request
curl -X DELETE https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/update-window \
-H 'Authorization: Bearer <your api token>'

GET /v1/profiles/{{profileId}}/extension-requirements

After having a profile created, in some situations we can need more specific information about it. In order to know which fields are required for a given profile, and to send the information over, we expose a few endpoints:

GET /v1/profiles/{{profileId}}/extension-requirements
POST /v1/profiles/{{profileId}}/extension-requirements

and

POST /v1/profiles/{{profileId}}/extensions
GET /v1/profiles/{{profileId}}/extensions

The GET and POST profile extension-requirements endpoints help you to figure out which fields are required to create a valid profile for different regions. You can use this data to build a dynamic user interface on top of these endpoints.

The POST and GET profile extensions endpoints allow you to send the extra profile information and retrieve it, respectively.

This format for dynamic forms is the same as the one used for recipient creation. See Recipient.Requirements

This is a step-by-step guide on how these endpoints work.

Using profile extension requirements

  1. First create a profile. See User Profiles Create (Personal) and User Profiles Create (Business)

  2. Call GET /v1/profiles/{{profileId}}/extension-requirements to get the list of fields you need to fill with values in the "details" section for adding information that will make a profile valid.

  3. Some fields require multiple levels of fields in the details request. This should be handled by the client based on the refreshRequirementsOnChange field. A top level field can have this field set to true, indicating that there are additional fields required depending on the selected value. To manage this you should create a request with all of the initially requested data and call the POST extension-requirements endpoint. You will be returned a response similar the previously returned data from GET extension-requirements but with additional fields.

  4. Once you have built your full profile extension details object you can add it to add information to the profile.

Building an user interface

When requesting the form data from the extension-requirements endpoint, the response defines different types of extensions that can be added. Each extension type then has multiple fields describing the form elements required to be shown to collect information from the user. Each field will have a type value, these tell you the field type that your front end needs to render to be able to collect the data. A number of field types are permitted, these are:

typeUI element
textA free text box
selectA selection box/dialog
radioA radio button choice between options
dateA text box with a date picker

Example data is also included in each field which should be shown to the user, along with a regex or min and max length constraints that should be applied as field level validations. You can optionally implement the dynamic validation using the validationAsync field, however these checks will also be done when a completed profile extension is submitted to POST /v1/profiles/{{profileId}}/extensions.

Response
typetext

"profile-extensions-requirements"

fields[n].nametext

Field description

fields[n].group[n].keytext

Key is name of the field you should include in the JSON

fields[n].group[n].typetext

Display type of field (e.g. text, select, etc)

fields[n].group[n].refreshRequirementsOnChangeboolean

Tells you whether you should call POST extension-requirements once the field value is set to discover required lower level fields.

fields[n].group[n].requiredboolean

Indicates if the field is mandatory or not

fields[n].group[n].displayFormattext

Display format pattern.

fields[n].group[n].exampletext

Example value.

fields[n].group[n].minLengthinteger

Min valid length of field value.

fields[n].group[n].maxLengthinteger

Max valid length of field value.

fields[n].group[n].validationRegexptext

Regexp validation pattern.

fields[n].group[n].validationAsynctext

Validator URL and parameter name you should use when submitting the value for validation

fields[n].group[n].valuesAllowed[n].keytext

List of allowed values. Value key

fields[n].group[n].valuesAllowed[n].nametext

List of allowed values. Value name.

Example Request - Get Extension Requirements
curl -X GET https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/extension-requirements \
-H 'Authorization: Bearer <your api token>'
Example Response
[
{
"type": "profile-extensions-requirements",
"usageInfo": null,
"fields": [
{
"name": "Tell us what you're using TransferWise for",
"group": [
{
"key": "accountPurpose",
"name": "Account Purpose",
"type": "select",
"refreshRequirementsOnChange": false,
"required": true,
"displayFormat": null,
"example": null,
"minLength": null,
"maxLength": null,
"validationRegexp": null,
"validationAsync": null,
"valuesAllowed": [
{
"key": "CONTRIBUTING_TO_PERSONAL_SAVINGS",
"name": "Contributing to personal savings"
},
{
"key": "GENERAL_MONTHLY_LIVING_EXPENSES",
"name": "General monthly living expenses"
},
{
"key": "INVESTING_IN_FUNDS_STOCKS_BONDS_OPTIONS_FUTURES_OR_OTHER",
"name": "Investing in funds stocks bonds options futures or other"
},
{
"key": "PAYING_FOR_GOODS_OR_SERVICES_ABROAD",
"name": "Paying for goods or services abroad"
},
{
"key": "PAYING_RENT_MORTGAGE_BANK_LOAN_INSURANCE_CREDIT",
"name": "Paying rent mortgage bank loan insurance credit"
},
{
"key": "PAYING_RENT_UTILITIES_OR_PROPERTY_CHARGES",
"name": "Paying rent utilities or property charges"
},
{
"key": "RECEIVE_SALARY_IN_DIFFERENT_CURRENCY",
"name": "Receive salary in different currency"
},
{
"key": "RECEIVE_PENSION_IN_DIFFERENT_CURRENCY",
"name": "Receive pension in different currency"
},
{
"key": "SENDING_MONEY_REGULARLY_TO_FAMILY",
"name": "Sending money regularly to family"
},
{
"key": "SENDING_MONEY_TO_MY_OWN_ACCOUNT_TO_BENEFIT_FROM_EXHCANGE_RATE",
"name": "Sending money to my own account to benefit from exchange rate"
}
]
}
]
}
]
}
]
Example Request - Post Extension Details
curl -X POST https://api.sandbox.transferwise.tech/v1/profiles/{{profileId}}/extensions \
-H 'Authorization: Bearer <your api token>' \
-H 'Content-Type: application/json' \
-d '{
"details": {
"accountPurpose": "SENDING_MONEY_REGULARLY_TO_FAMILY"
}
}'

You can check the verification status of a profile using the following API. This is a profile-specific API resource which should be accessed using an access token acquired for the profile.

Response

source_currencytext

ISO 4217 currency code.

current_statusverification status code (see below)

Current verification status

maximum_entitled_amountdecimal

Maximum entitled amount that can be transferred with the user's given verification state.

Guide on how to process the API response

current_statusmaximum_entitled_amountHow to process
verifiedany valueProfile is verified. maximum_entitled_amount field can be ignored (note that some regional limits may still apply).
not_verified0Profile is not verified. Any payments from the user will be delayed by verification.
not_verified> 0Profile is not verified yet but the user is allowed to make payments up to a certain limit. Once the limit is reached, following payments might be delayed because of additional verification requirements. Please note that the limit is cumulative and not per transfer. This state might allow some users to experience the product immediately even if the verification process isn't complete yet.
Verification status codeDescription
verifiedThe profile is sufficiently verified to start making payments (note that some regional limits may still apply)
not_verifiedThe profile is currently awaiting verification or there are pending issues with the verification process

Please note that we do not expose any finer details of customer verification.

Example Request
curl -X POST 'https://api.sandbox.transferwise.tech/v3/profiles/{{profileId}}/verification-status/bank-transfer?source_currencies={{currency_array}}' \
-H "Authorization: Bearer <your API token>"
Example Response
{
"routes": [
{
"source_currency": "GBP",
"maximum_entitled_amount": 100000,
"current_status": "verified"
},
{
"source_currency": "USD",
"maximum_entitled_amount": 0,
"current_status": "not_verified"
},
{
"source_currency": "EUR",
"maximum_entitled_amount": 10000,
"current_status": "not_verified"
}
],
"request_id": "e66da5f6-2456-403c-bfcb-908885ee1a61"
}