Wise user API

openapi: 3.2.0
info:
  title: Wise Platform User API
  version: ''
  description: "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.\n{% admonition type=\"success\" name=\"New to wise?\" %}\n  We strongly recommend first reading our **[Getting Started Guide](/guides/developer/index.md)** to help you set up credentials and make your first call.\n{% /admonition %}\n\nBefore you begin {% .title-2 .m-t-5 %}\n\nTo use this API reference effectively, you should have:\n\n- Received Valid [API credentials from Wise](/guides/developer/auth-and-security/index.md) (Client ID and Client Secret)\n- Understand OAuth 2.0 authentication\n- Be familiar with RESTful API concepts\n\nCore API resources {% .title-2 .m-t-5 .m-b-0 %}\n\n| Resource | Purpose |\n|----------|---------|\n| **[Quote](/api-reference/quote)** | Exchange rate and fee calculations |\n| **[Recipient](/api-reference/recipient)** | Beneficiary account management |\n| **[Transfer](/api-reference/transfer)** | Payment creation and execution |\n| **[Balance](/api-reference/balance)** | Multi-currency account operations |\n| **[Profile](/api-reference/profile)** | Account ownership details |\n| **[Rate](/api-reference/rate)** | Current and historical exchange rates |\n\n**Not sure which workflow to build?**<br>\nStart with our [Integration Guides](/guides/product/send-money/use-cases/index.md) for step-by-step implementation examples.{% .m-t-3 .m-b-5 %}\n"
servers:
- url: https://api.wise.com
  description: Production Environment
- url: https://api.wise-sandbox.com
  description: Sandbox Environment
tags:
- name: user
  x-displayName: Users
  description: 'A User serves as the primary entity and can possess multiple Profiles to represent different contexts or settings.

    A User can have one personal Profile and multiple business Profiles.

    Each [Profile](/api-reference/profile) — whether personal or business — can have its own [multi-currency account](/api-reference/multi-currency-account),

    enabling transactions across various currencies. This hierarchical structure allows for flexible management of user settings and financial operations,

    accommodating both personal and business needs.


    ![User profile structure](/images/diagrams/user-profile-structure.svg)

    '
paths:
  /v1/me:
    get:
      tags:
      - user
      summary: Retrieve current user by token
      operationId: userGetByToken
      description: 'Get authenticated user details for the user''s token submitted in the Authorization header.

        '
      security:
      - UserToken: []
      - PersonalToken: []
      responses:
        '200':
          description: OK - Successfully retrieved user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
          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'
  /v1/users/{userId}:
    get:
      tags:
      - user
      summary: Retrieve a user by ID
      operationId: userGetById
      description: 'Get authenticated user details by user ID.

        '
      security:
      - UserToken: []
      - PersonalToken: []
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: The user ID.
        example: 101
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: OK - Successfully retrieved user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
          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/user/signup/registration_code:
    post:
      tags:
      - user
      summary: Create a user with a registration code
      operationId: userCreate
      description: 'Wise uses email address as unique identifier for users. If email is new (there is no active user already) then a new user will be created.


        When you are submitting an email which already exists amongst our users then you will get a warning that "You''re already a member. Please login". If user already exists then you need to redirect to "Get user authorization" webpage.

        '
      security:
      - ClientCredentialsToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - registrationCode
              properties:
                email:
                  type: string
                  format: email
                  description: New user's email address.
                  example: user@email.com
                registrationCode:
                  type: string
                  minLength: 32
                  description: 'Randomly generated registration code that is unique to this user and request. At least 32 characters long.

                    You need to store registration code to obtain access token on behalf of this newly created user in next step.

                    Please apply the same security standards to handling registration code as if it was a password.

                    '
                  example: a]#Et6(yLW@mq4Ky_+EAjXxpHGq7*&lr
                language:
                  type: string
                  description: 'User default language for UI and email communication.

                    Allowed values: EN, US, PT, ES, FR, DE, IT, JA, RU, PL, HU, TR, RO, NL, HK.

                    Default value: EN.

                    '
                  example: EN
      responses:
        '200':
          description: OK - User is created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
              example:
                id: 12345
                name: null
                email: new.user@domain.com
                active: true
                details: null
          headers:
            X-External-Correlation-Id:
              $ref: '#/components/headers/X-External-Correlation-Id'
            x-trace-id:
              $ref: '#/components/headers/x-trace-id'
        '409':
          description: Conflict - User already exists.
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                        path:
                          type: string
                        arguments:
                          type: array
                          items:
                            type: string
              example:
                errors:
                - code: NOT_UNIQUE
                  message: You're already a member. Please login
                  path: email
                  arguments:
                  - email
                  - class com.transferwise.fx.api.ApiRegisterCommand
                  - existing.user@domain.com
          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'
  /v1/users/exists:
    post:
      tags:
      - user
      summary: Check if user exists
      operationId: userCheckExists
      description: 'Check if a user already exists by email. Wise uses email address as unique identifier for users. If email has already been used by a user, it cannot be reused to create a new user.


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

        '
      security:
      - ClientCredentialsToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  description: User's email address.
                  example: test@wise.com
      responses:
        '200':
          description: OK - Successfully checked user existence.
          content:
            application/json:
              schema:
                type: object
                properties:
                  exists:
                    type: boolean
                    description: Whether a user with this email already exists.
              example:
                exists: true
          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'
  /v1/users/{userId}/contact-email:
    put:
      tags:
      - user
      summary: Set a contact email address
      operationId: userContactEmailSet
      description: 'Sets a contact email address. The contact email address is used to send notifications to users who have been registered with a dummy email address.

        '
      security:
      - UserToken: []
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: The user ID.
        example: 101
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  format: email
                  description: Contact email address.
                  example: new-user@email.com
      responses:
        '200':
          description: OK - Contact email address set successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    format: email
                    description: Contact email address.
              example:
                email: new-user@email.com
          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'
    get:
      tags:
      - user
      summary: Retrieve a contact email address
      operationId: userContactEmailGet
      description: Retrieves a contact email address.
      security:
      - UserToken: []
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: The user ID.
        example: 101
      - $ref: '#/components/parameters/X-External-Correlation-Id'
      responses:
        '200':
          description: OK - Successfully retrieved contact email address.
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    format: email
                    description: Contact email address.
              example:
                email: new-user@email.com
          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'
components:
  schemas:
    user:
      title: User
      type: object
      x-tags:
      - user
      description: Represents a Wise user account.
      properties:
        id:
          type: integer
          format: int64
          description: User ID.
          example: 101
        name:
          type:
          - string
          - 'null'
          description: User's full name.
          example: Example Person
        email:
          type: string
          description: User's email.
          example: person@example.com
        active:
          type: boolean
          description: If user is active or not.
          example: true
        details:
          type:
          - object
          - 'null'
          description: User details.
          properties:
            firstName:
              type: string
              description: User's first name.
              example: Example
            lastName:
              type: string
              description: User's last name.
              example: Person
            phoneNumber:
              type: string
              description: Phone number.
              example: '+37111111111'
            dateOfBirth:
              type: string
              format: date
              description: Date of birth (YYYY-MM-DD).
              example: '1977-01-01'
            occupation:
              type: string
              description: Person's occupation.
              example: ''
            avatar:
              type: string
              description: Link to person avatar image.
              example: https://lh6.googleusercontent.com/photo.jpg
            primaryAddress:
              type: integer
              format: int64
              description: Address object ID to use in addresses endpoints.
              example: 111
            address:
              type: object
              description: User's address.
              properties:
                countryCode:
                  type: string
                  description: Address country code in 2 digits. "US" for example.
                  example: EE
                firstLine:
                  type: string
                  description: Address first line.
                  example: Road 123
                postCode:
                  type: string
                  description: Address post code.
                  example: '11111'
                city:
                  type: string
                  description: Address city name.
                  example: Tallinn
                state:
                  type: string
                  description: Address state code. Required if country is US, CA, AU, or BR.
                  example: ''
                occupation:
                  type: string
                  description: User occupation. Required for US, CA, JP.
                  example: ''
  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
  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
  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
  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