Wise

Wise Address API

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.

GitHub OpenAPI

Operations 5

POST /v1/addresses Create or Update an Address #
GET /v1/addresses List Addresses for a Profile #
GET /v1/addresses/{addressId} Retrieve an Address by ID #
GET /v1/address-requirements Get Address Requirements #
POST /v1/address-requirements Get Address Requirements (with context) #

Documentation

📖
Documentation
https://docs.wise.com/api-docs/api-reference/profile
📖
Documentation
https://docs.wise.com/api-docs/api-reference/recipient
📖
Documentation
https://docs.wise.com/api-docs/api-reference/quote
📖
Documentation
https://docs.wise.com/api-docs/api-reference/transfer
📖
Documentation
https://docs.wise.com/api-docs/api-reference/balance
📖
Documentation
https://docs.wise.com/api-docs/api-reference/multi-currency-account
📖
Documentation
https://docs.wise.com/api-docs/api-reference/balance-statement
📖
Documentation
https://docs.wise.com/api-docs/api-reference/card
📖
Documentation
https://docs.wise.com/api-docs/api-reference/subscription
📖
Documentation
https://docs.wise.com/api-docs/api-reference/simulation

Specifications

⚙
OpenAPI
https://artifacts.apis.io/wise/openapi/wise-address-api-openapi.yml
⚙
AsyncAPI
https://artifacts.apis.io/wise/asyncapi/wise-webhooks-asyncapi.yml

Other Resources

🔗
Sandbox
https://api.sandbox.transferwise.tech

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/wise:wise-address-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

wise-address-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Wise Platform Address API
  version: ''
  description: The Wise Platform API is a REST-based interface that enables programmatic access to Wise's payment infrastructure.
servers:
- url: https://api.wise.com
  description: Production Environment
- url: https://api.wise-sandbox.com
  description: Sandbox Environment
tags:
- name: Address
  x-displayName: Addresses
  description: '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.'
paths:
  /v1/addresses:
    post:
      tags:
      - Address
      summary: Create or Update an Address
      operationId: addressCreate
      description: '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: []
      - PersonalToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressRequest'
      responses:
        '200':
          description: OK - Address successfully created or updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
              example:
                id: 10000001
                profile: 12345678
                details:
                  country: US
                  state: AZ
                  city: Phoenix
                  postCode: '10025'
                  firstLine: 50 Sunflower Ave
                  occupations:
                  - code: Software Engineer
                    format: FREE_FORM
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
      parameters:
      - $ref: '#/components/parameters/X-External-Correlation-Id'
    get:
      tags:
      - Address
      summary: List Addresses for a Profile
      operationId: addressList
      description: List of addresses belonging to user profile.
      security:
      - UserToken: []
      - PersonalToken: []
      parameters:
      - name: profile
        in: query
        example: 12345678
        schema:
          type: integer
          format: int64
        description: The profile ID to list addresses for.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: OK - Successfully retrieved addresses.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Address'
              example:
              - id: 10000001
                profile: 12345678
                details:
                  country: US
                  state: AZ
                  city: Phoenix
                  postCode: '10025'
                  firstLine: 50 Sunflower Ave
                  occupations:
                  - code: Software Engineer
                    format: FREE_FORM
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v1/addresses/{addressId}:
    get:
      tags:
      - Address
      summary: Retrieve an Address by ID
      operationId: addressGet
      description: Get address info by ID.
      security:
      - UserToken: []
      - PersonalToken: []
      parameters:
      - name: addressId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: The unique identifier of the address.
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: OK - Successfully retrieved the address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
              example:
                id: 10000001
                profile: 12345678
                details:
                  country: US
                  state: AZ
                  city: Phoenix
                  postCode: '10025'
                  firstLine: 50 Sunflower Ave
                  occupations:
                  - code: Software Engineer
                    format: FREE_FORM
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
  /v1/address-requirements:
    get:
      tags:
      - Address
      summary: Get Address Requirements
      operationId: addressRequirementsGet
      description: '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: []
      - PersonalToken: []
      responses:
        '200':
          description: OK - Successfully retrieved address requirements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressRequirementsResponse'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
      parameters:
      - $ref: '#/components/parameters/X-External-Correlation-Id'
    post:
      tags:
      - Address
      summary: Get Address Requirements (with context)
      operationId: addressRequirementsPost
      description: '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: []
      - PersonalToken: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressRequirementsRequest'
            example:
              details:
                country: US
      responses:
        '200':
          description: OK - Successfully retrieved address requirements.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressRequirementsResponse'
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '429':
          $ref: '#/components/responses/429'
      parameters:
      - $ref: '#/components/parameters/X-External-Correlation-Id'
components:
  schemas:
    AddressRequirementsRequest:
      type: object
      description: Request body for retrieving address requirements based on context.
      required:
      - details
      properties:
        profile:
          type: integer
          format: int64
          description: User profile ID.
          example: 12345678
        details:
          type: object
          description: Address details to provide context for requirements lookup. Additional fields beyond those listed are accepted.
          required:
          - country
          properties:
            country:
              type: string
              description: Country code (ISO 3166-2 Country Code).
              example: US
            state:
              type: string
              description: State code. Provide to discover state-dependent fields.
              example: AZ
          additionalProperties:
            type: string
            description: Any other properties to provide context for the requirements lookup.
    Address:
      type: object
      x-tags:
      - address
      description: Represents a physical address associated with a profile.
      properties:
        id:
          type: integer
          format: int64
          description: Address ID.
          example: 10000001
        profile:
          type: integer
          format: int64
          description: User profile ID.
          example: 12345678
        details:
          type: object
          description: Address details.
          properties:
            country:
              type: string
              description: Country code (ISO 3166-2 Country Code).
              example: US
            firstLine:
              type: string
              description: 'Address line: street, house, apartment.'
              example: 50 Sunflower Ave
            postCode:
              type: string
              description: Postal or zip code (max 30 characters).
              maxLength: 30
              example: '10025'
            city:
              type: string
              description: City name.
              example: Phoenix
            state:
              type: string
              description: State code. Required if country is US, CA, BR, or AU.
              example: AZ
            occupations:
              type: array
              description: User occupations. Required for CA, IN, JP, ID, IL, MX, and within the US for state NM.
              items:
                type: object
                properties:
                  code:
                    type: string
                    description: User occupation - any value permitted.
                    example: Software Engineer
                  format:
                    type: string
                    description: Occupation type - always `FREE_FORM`.
                    enum:
                    - FREE_FORM
                    example: FREE_FORM
    AddressRequest:
      type: object
      description: Request payload for creating or updating an address.
      required:
      - profile
      - details
      properties:
        profile:
          type: integer
          format: int64
          description: User profile ID.
          example: 12345678
        details:
          type: object
          description: Address details.
          required:
          - country
          - firstLine
          - postCode
          - city
          properties:
            country:
              type: string
              description: Country code (ISO 3166-1 alpha-2).
              example: US
            firstLine:
              type: string
              description: 'Address line: street, house, apartment.'
              example: 50 Sunflower Ave
            postCode:
              type: string
              description: Postal / zip code (max 30 characters).
              maxLength: 30
              example: '10025'
            city:
              type: string
              description: City name.
              example: Phoenix
            state:
              type: string
              description: State code. Required if country is US, CA, BR, or AU.
              example: AZ
            occupations:
              type: array
              description: User occupations. Required for CA, IN, JP, ID, IL, MX, and within the US for state NM.
              items:
                type: object
                properties:
                  code:
                    type: string
                    description: User occupation - any value permitted.
                    example: Software Engineer
                  format:
                    type: string
                    description: Occupation type - always `FREE_FORM`.
                    enum:
                    - FREE_FORM
                    example: FREE_FORM
    AddressRequirementsResponse:
      type: array
      items:
        type: object
        properties:
          type:
            type: string
            description: Always "address".
            example: address
          fields:
            type: array
            description: List of fields required for the address.
            items:
              type: object
              properties:
                name:
                  type: string
                  description: Display name of the field.
                  example: Country
                group:
                  type: array
                  items:
                    type: object
                    properties:
                      key:
                        type: string
                        description: Key name to include in the JSON request.
                        example: country
                      type:
                        type: string
                        description: Display type of field.
                        enum:
                        - text
                        - select
                        example: select
                      refreshRequirementsOnChange:
                        type: boolean
                        description: If true, call POST address-requirements when this field value changes to discover additional required fields.
                        example: true
                      required:
                        type: boolean
                        description: Indicates if the field is mandatory.
                        example: true
                      displayFormat:
                        type:
                        - string
                        - 'null'
                        description: Display format pattern.
                        example: null
                      example:
                        type: string
                        description: Example value to help users understand what to input.
                        example: Germany
                      minLength:
                        type:
                        - integer
                        - 'null'
                        format: int32
                        description: Minimum valid length of field value.
                        example: null
                      maxLength:
                        type:
                        - integer
                        - 'null'
                        format: int32
                        description: Maximum valid length of field value.
                        example: null
                      validationRegexp:
                        type:
                        - string
                        - 'null'
                        description: Regexp validation pattern.
                        example: null
                      validationAsync:
                        type:
                        - string
                        - 'null'
                        description: Deprecated. This validation will instead be performed when submitting the request.
                        deprecated: true
                        example: null
                      valuesAllowed:
                        type: array
                        description: List of allowed values (for select fields).
                        example:
                        - key: US
                          name: United States
                        - key: GB
                          name: United Kingdom
                        items:
                          type: object
                          properties:
                            key:
                              type: string
                              description: Value key to use in the request.
                            name:
                              type: string
                              description: Display name for the value.
  headers:
    X-External-Correlation-Id:
      x-global: true
      description: Echoed back when `X-External-Correlation-Id` was included in the request. [Learn more](/guides/developer/headers/correlation-id).
      schema:
        type: string
        format: uuid
        maxLength: 36
      example: f47ac10b-58cc-4372-a567-0e02b2c3d479
    x-trace-id:
      x-global: true
      description: Unique trace identifier assigned by Wise. Useful when contacting support about a specific request.
      schema:
        type: string
      example: fba501b6d453b96789f52338f019341f
  parameters:
    X-External-Correlation-Id:
      x-global: true
      name: X-External-Correlation-Id
      in: header
      required: false
      description: '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).

        '
      schema:
        type: string
        format: uuid
        maxLength: 36
      example: f47ac10b-58cc-4372-a567-0e02b2c3d479
  responses:
    '429':
      x-global: true
      description: Rate limit exceeded. Retry after the number of seconds specified in the `Retry-After` header.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          schema:
            type: integer
          example: 5
        X-Rate-Limited-By:
          description: Identifies the rate limiter that triggered the 429 response.
          schema:
            type: string
          example: wise-public-api
        X-External-Correlation-Id:
          $ref: '#/components/headers/X-External-Correlation-Id'
        x-trace-id:
          $ref: '#/components/headers/x-trace-id'
      content:
        application/json:
          schema:
            type: object
  securitySchemes:
    UserToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'User Access Token for making API calls on behalf of a Wise user.


        Can be obtained via two OAuth 2.0 flows:

        - **registration_code grant**: For partners creating users via API

        - **authorization_code grant**: For partners using Wise''s authorization page


        Access tokens are valid for 12 hours and can be refreshed using a refresh token.

        '
    PersonalToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Personal API Token for individual personal or small business users.

        Generated from Wise.com > Settings > Connect and manage apps > API tokens.

        Has limited API access compared to OAuth tokens (PSD2 restrictions apply for EU/UK users).

        '
    ClientCredentialsToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Application-level token for partner operations that don''t require a specific user context, such as bulk settlement and card spend controls.


        Obtained via `POST /oauth/token` with Basic Authentication (client-id:client-secret) and `grant_type=client_credentials`.


        Valid for 12 hours. No refresh token — fetch a new token when expired.


        See [create an OAuth token](/api-reference/oauth-token/oauthtokencreate) for details.

        '
    BasicAuth:
      type: http
      scheme: basic
      description: 'Basic Authentication using your Client ID and Client Secret as the username and password.


        Client credentials are provided by Wise when your partnership begins. See [Getting Started](/guides/developer) for details.

        '
x-tagGroups:
- name: Authentication
  tags:
  - oauth-token
- name: Enhanced Security
  tags:
  - jose
- name: Users
  tags:
  - user
  - claim-account
- name: Profiles
  tags:
  - profile
  - activity
  - address
- name: Verification
  tags:
  - kyc-review
  - verification
  - facetec
- name: Strong Customer Authentication
  tags:
  - sca-ott
  - sca-sessions
  - sca-pin
  - sca-facemaps
  - sca-device-fingerprints
  - sca-otp
  - user-security
- name: Balances
  tags:
  - balance
  - balance-statement
  - bank-account-details
  - multi-currency-account
- name: Cards
  tags:
  - card
  - card-sensitive-details
  - 3ds
  - card-kiosk-collection
  - card-order
  - card-transaction
  - spend-limits
  - spend-controls
  - digital-wallet
  - disputes
- name: Quotes
  tags:
  - quote
  - rate
  - comparison
- name: Recipients
  tags:
  - recipient
  - contact
- name: Transfers
  tags:
  - transfer
  - delivery-estimate
  - currencies
  - batch-group
- name: Funding
  tags:
  - payin-deposit-detail
  - direct-debit-account
  - bulk-settlement
  - payins
- name: Webhooks
  tags:
  - webhook
  - webhook-event
- name: Simulations
  tags:
  - simulation
- name: Partner Support
  tags:
  - case