Skip to content

Wise Platform API

The Wise Platform API is a REST-based interface that enables programmatic access to Wise's payment infrastructure. All endpoints return JSON-formatted responses and use standard HTTP methods and status codes.

New to wise?

We strongly recommend first reading our Getting Started Guide to help you set up credentials and make your first call.

Before you begin

To use this API reference effectively, you should have:

  • Received Valid API credentials from Wise (Client ID and Client Secret)
  • Understand OAuth 2.0 authentication
  • Be familiar with RESTful API concepts

Core API resources

ResourcePurpose
QuoteExchange rate and fee calculations
RecipientBeneficiary account management
TransferPayment creation and execution
BalanceMulti-currency account operations
ProfileAccount ownership details
RateCurrent and historical exchange rates

Not sure which workflow to build?
Start with our Integration Guides for step-by-step implementation examples.

Languages
Servers
Production Environment
https://api.wise.com/
Sandbox Environment
https://api.wise-sandbox.com/

3D Secure Authentication

To manage certain aspects of the 3D Secure (3DS) authentication, you will need to integrate with the following APIs.

Operations

Activity

Activity represents a snapshot of a performed action for a profile.

Operations

Additional Customer Verification

In certain situations, additional evidence is required to verify customers and ensure we’re compliant with the KYC regulations.

Additional Verification APIs support a list of evidences that can be found in the Supported Evidences guide.

If you use the Customer Account with Partner KYC model and your customers are primarily based in the EU, refer to this Onboarding EU customers guide for instructions on how to use these APIs.

If you use the Customer Account with Partner KYC model and you are onboarding high risk business customers based primarily based in the US, refer to this Onboarding High Risk US Businesses guide for instructions on how to use these APIs.

Operations

Address

Manage physical addresses associated with user profiles.

Address requirements vary by country — use the address requirements endpoints to dynamically discover which fields are needed before creating an address.

SchemasOperations

Address

Represents a physical address associated with a profile.

idinteger(int64)

Address ID.

Example: 10000001
profileinteger(int64)

User profile ID.

Example: 12345678
detailsobject

Address details.

details.​countrystring

Country code (ISO 3166-2 Country Code).

Example: "US"
details.​firstLinestring

Address line: street, house, apartment.

Example: "50 Sunflower Ave"
details.​postCodestring<= 30 characters

Postal or zip code (max 30 characters).

Example: "10025"
details.​citystring

City name.

Example: "Phoenix"
details.​statestring

State code. Required if country is US, CA, BR, or AU.

Example: "AZ"
details.​occupationsArray of objects

User occupations. Required for CA, IN, JP, ID, IL, MX, and within the US for state NM.

{
  "id": 10000001,
  "profile": 12345678,
  "details": {
    "country": "US",
    "firstLine": "50 Sunflower Ave",
    "postCode": "10025",
    "city": "Phoenix",
    "state": "AZ",
    "occupations": [
      { … }
    ]
  }
}

Create or Update an Address

Request

Adds address info to user profile.

List of required fields are different for different countries. Use the address requirements endpoint to dynamically discover required fields.

For updating personal profiles, consider using the personal profile update endpoint instead. It allows submitting the address information alongside other profile data.

State field is required for US, CA, BR, and AU addresses.

Occupations is required for CA, IN, JP, ID, IL, MX, and within the US for the state NM.

Security
UserToken or PersonalToken
Bodyapplication/jsonrequired
profileinteger(int64)required

User profile ID.

Example: 12345678
detailsobjectrequired

Address details.

details.​countrystringrequired

Country code (ISO 3166-1 alpha-2).

Example: "US"
details.​firstLinestringrequired

Address line: street, house, apartment.

Example: "50 Sunflower Ave"
details.​postCodestring<= 30 charactersrequired

Postal / zip code (max 30 characters).

Example: "10025"
details.​citystringrequired

City name.

Example: "Phoenix"
details.​statestring

State code. Required if country is US, CA, BR, or AU.

Example: "AZ"
details.​occupationsArray of objects

User occupations. Required for CA, IN, JP, ID, IL, MX, and within the US for state NM.

curl -i -X POST \
  https://api.wise.com/v1/addresses \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "profile": 12345678,
    "details": {
      "country": "US",
      "firstLine": "50 Sunflower Ave",
      "postCode": "10025",
      "city": "Phoenix",
      "state": "AZ",
      "occupations": [
        {
          "code": "Software Engineer",
          "format": "FREE_FORM"
        }
      ]
    }
  }'

Responses

OK - Address successfully created or updated.

Bodyapplication/json
idinteger(int64)

Address ID.

Example: 10000001
profileinteger(int64)

User profile ID.

Example: 12345678
detailsobject

Address details.

details.​countrystring

Country code (ISO 3166-2 Country Code).

Example: "US"
details.​firstLinestring

Address line: street, house, apartment.

Example: "50 Sunflower Ave"
details.​postCodestring<= 30 characters

Postal or zip code (max 30 characters).

Example: "10025"
details.​citystring

City name.

Example: "Phoenix"
details.​statestring

State code. Required if country is US, CA, BR, or AU.

Example: "AZ"
details.​occupationsArray of objects

User occupations. Required for CA, IN, JP, ID, IL, MX, and within the US for state NM.

Response
application/json
{
  "id": 10000001,
  "profile": 12345678,
  "details": {
    "country": "US",
    "state": "AZ",
    "city": "Phoenix",
    "postCode": "10025",
    "firstLine": "50 Sunflower Ave",
    "occupations": [
      { … }
    ]
  }
}

List Addresses for a Profile

Request

List of addresses belonging to user profile.

Security
UserToken or PersonalToken
Query
profileinteger(int64)

The profile ID to list addresses for.

Example: profile=12345678
curl -i -X GET \
  'https://api.wise.com/v1/addresses?profile=12345678' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK - Successfully retrieved addresses.

Bodyapplication/jsonArray [
idinteger(int64)

Address ID.

Example: 10000001
profileinteger(int64)

User profile ID.

Example: 12345678
detailsobject

Address details.

details.​countrystring

Country code (ISO 3166-2 Country Code).

Example: "US"
details.​firstLinestring

Address line: street, house, apartment.

Example: "50 Sunflower Ave"
details.​postCodestring<= 30 characters

Postal or zip code (max 30 characters).

Example: "10025"
details.​citystring

City name.

Example: "Phoenix"
details.​statestring

State code. Required if country is US, CA, BR, or AU.

Example: "AZ"
details.​occupationsArray of objects

User occupations. Required for CA, IN, JP, ID, IL, MX, and within the US for state NM.

]
Response
application/json
[
  {
    "id": 10000001,
    "profile": 12345678,
    "details": {
      "country": "US",
      "state": "AZ",
      "city": "Phoenix",
      "postCode": "10025",
      "firstLine": "50 Sunflower Ave",
      "occupations": [ … ]
    }
  }
]

Retrieve an Address by ID

Request

Get address info by ID.

Security
UserToken or PersonalToken
Path
addressIdinteger(int64)required

The unique identifier of the address.

curl -i -X GET \
  'https://api.wise.com/v1/addresses/{addressId}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK - Successfully retrieved the address.

Bodyapplication/json
idinteger(int64)

Address ID.

Example: 10000001
profileinteger(int64)

User profile ID.

Example: 12345678
detailsobject

Address details.

details.​countrystring

Country code (ISO 3166-2 Country Code).

Example: "US"
details.​firstLinestring

Address line: street, house, apartment.

Example: "50 Sunflower Ave"
details.​postCodestring<= 30 characters

Postal or zip code (max 30 characters).

Example: "10025"
details.​citystring

City name.

Example: "Phoenix"
details.​statestring

State code. Required if country is US, CA, BR, or AU.

Example: "AZ"
details.​occupationsArray of objects

User occupations. Required for CA, IN, JP, ID, IL, MX, and within the US for state NM.

Response
application/json
{
  "id": 10000001,
  "profile": 12345678,
  "details": {
    "country": "US",
    "state": "AZ",
    "city": "Phoenix",
    "postCode": "10025",
    "firstLine": "50 Sunflower Ave",
    "occupations": [
      { … }
    ]
  }
}

Get Address Requirements

Request

Returns the list of fields required to create a valid address. Use this as a starting point to discover required fields.

The response contains 4 required top-level fields:

  • country (select field with list of values)
  • city (text field)
  • postCode (text field)
  • firstLine (text field)

If a field has refreshRequirementsOnChange: true, call the POST endpoint with that field's value to discover additional required fields.

For a step-by-step walkthrough, see the Address Requirements guide.

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

Responses

OK - Successfully retrieved address requirements.

Bodyapplication/jsonArray [
typestring

Always "address".

Example: "address"
fieldsArray of objects

List of fields required for the address.

fields[].​namestring

Display name of the field.

Example: "Country"
fields[].​groupArray of objects
]
Response
application/json
[
  {
    "type": "address",
    "fields": [
      { … }
    ]
  }
]

Get Address Requirements (with context)

Request

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.

Security
UserToken or PersonalToken
Bodyapplication/json
profileinteger(int64)

User profile ID.

Example: 12345678
detailsobjectrequired

Address details to provide context for requirements lookup. Additional fields beyond those listed are accepted.

details.​countrystringrequired

Country code (ISO 3166-2 Country Code).

Example: "US"
details.​statestring

State code. Provide to discover state-dependent fields.

Example: "AZ"
details.​property name*stringadditional property

Any other properties to provide context for the requirements lookup.

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"
    }
  }'

Responses

OK - Successfully retrieved address requirements.

Bodyapplication/jsonArray [
typestring

Always "address".

Example: "address"
fieldsArray of objects

List of fields required for the address.

fields[].​namestring

Display name of the field.

Example: "Country"
fields[].​groupArray of objects
]
Response
application/json
[
  {
    "type": "address",
    "fields": [
      { … }
    ]
  }
]

Balance

Create and manage balance accounts within a multi-currency account.

Each profile can hold multiple balance accounts in different currencies. A STANDARD balance is limited to one per currency, while SAVINGS balances (Jars) allow multiple in the same currency. Creating the first balance for a profile automatically creates the multi-currency account.

Balances include an investmentState field. Only balances with NOT_INVESTED can be operated on via the API. Invested balances should be shown but not actionable.

For a complete guide on multi-currency accounts, see Multi-Currency Accounts.

SchemasOperations

Balance Statement

Balance statements contain transactional activities on a Wise Multi-Currency Account, including deposits, withdrawals, conversions, card transactions, and fees.

Statements can be retrieved in multiple formats: JSON, CSV, PDF, XLSX, CAMT.053, MT940, or QIF.

Operations