Skip to content

OTP

For phone-based OTP (one-time password) authentication — where an OTP is a single-use 6-digit code sent to verify the identity of a user — Wise supports multiple delivery methods, including SMS, WhatsApp, and voice. Use Wise's secure endpoint to create and register the end user's phone number. Then, call the trigger endpoints (SMS, WhatsApp, Voice) to send an OTP to the registered number. Finally, submit the OTP via the verify endpoints (SMS, WhatsApp, Voice) to complete the authentication challenge.

Please read the SCA over API guide to understand how SCA integration works.

Operations

Create Phone Number

Request

Create a verified phone number for a user.

This endpoint is restricted and requires both a client credentials token and additional access to use. Please speak with your implementation manager if you would like to use this API.

Security
ClientCredentialsToken
Path
userIdinteger, (int64)required

User ID.

Headers
X-External-Correlation-Idstring, (uuid), <= 36 characters

Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more.

Example:f47ac10b-58cc-4372-a567-0e02b2c3d479
Bodyapplication/jsonrequired
phoneNumberstring

A valid phone number in string.

curl -i -X POST \
  'https://api.wise.com/2026Q3/application/users/{userId}/phone-numbers' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-External-Correlation-Id: f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  -d '{
    "phoneNumber": "string"
  }'

Responses

OK

Headers
X-External-Correlation-Idstring, (uuid), <= 36 characters

Echoed back when X-External-Correlation-Id was included in the request. Learn more.

Example:"f47ac10b-58cc-4372-a567-0e02b2c3d479"
x-trace-idstring

Unique trace identifier assigned by Wise. Useful when contacting support about a specific request.

Example:"fba501b6d453b96789f52338f019341f"
Bodyapplication/json
idinteger, (int64)

ID of the phone number.

Example:1230944
phoneNumberstring

A text representation of phone number.

Example:"+6588888888"
typestring

Type of phone number when used in authentication.

Only PRIMARY is supported at the moment.

Example:"PRIMARY"
verifiedboolean

Indicator if phone number is verified.

Example:true
clientIdstring

Client ID of which this phone number belongs to.

Example:"clientId"
Response
{
  "id": 1230944,
  "phoneNumber": "+6588888888",
  "type": "PRIMARY",
  "verified": true,
  "clientId": "clientId"
}