Verification Service - IdCanopy API Documentation

curl --request POST \
  --url https://api-umbrella.io/api/services/phone-service/verification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phoneNumber": "436501234567",
  "method": "email",
  "email": "test@test.com",
  "externalId": "12312",
  "securityFactor": "12345"
}
'

{
  "status": true,
  "data": {
    "mobileAppToken": "a1378b455f3048059a7be9df6a9da3aa",
    "recipient": {
      "phoneNumber": "436501234567"
    },
    "referenceId": "366691874BD00250933424F72F7C50CB",
    "state": "CREATED",
    "status": {
      "code": 3901,
      "description": "Request in progress",
      "updatedOn": "2025-10-02T10:04:58.505000Z"
    }
  }
}

{
  "message": "Invalid request payload"
}

{
  "message": "Unauthorized request"
}

{
  "message": "Journey not found"
}

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded.",
  "code": "429"
}

{
  "message": "Internal Server Error"
}

{
  "error": "Service Unavailable",
  "message": "Service is unavailable.",
  "code": "503"
}

POST

phone-service

verification

curl --request POST \
  --url https://api-umbrella.io/api/services/phone-service/verification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phoneNumber": "436501234567",
  "method": "email",
  "email": "test@test.com",
  "externalId": "12312",
  "securityFactor": "12345"
}
'

{
  "status": true,
  "data": {
    "mobileAppToken": "a1378b455f3048059a7be9df6a9da3aa",
    "recipient": {
      "phoneNumber": "436501234567"
    },
    "referenceId": "366691874BD00250933424F72F7C50CB",
    "state": "CREATED",
    "status": {
      "code": 3901,
      "description": "Request in progress",
      "updatedOn": "2025-10-02T10:04:58.505000Z"
    }
  }
}

{
  "message": "Invalid request payload"
}

{
  "message": "Unauthorized request"
}

{
  "message": "Journey not found"
}

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded.",
  "code": "429"
}

{
  "message": "Internal Server Error"
}

{
  "error": "Service Unavailable",
  "message": "Service is unavailable.",
  "code": "503"
}

For a usage description of the Verification Service, please refer to the Verification page.

Endpoint

POST /phone-service/verification

Swagger

Authorizations

Authorization

string

header

required

Bearer token obtained from POST /auth. Valid for 60 minutes.

Body

application/json

Option 1
Option 2

method

enum<string>

required

The delivery method to use.

Available options:

sms,

email

Allowed value: "sms"

Example:

"email"

phoneNumber

string

required

Recipient's phone number in international format, no spaces or special characters. Required if method = sms.

Required string length: 6 - 20

Pattern: ^[0-9]+$

Example:

"436501234567"

string<email>

Recipient's email address. Required if method = email.

Example:

"test@test.com"

securityFactor

string

A custom numeric OTP (3–10 digits). If omitted, a 6-digit OTP is auto-generated.

Pattern: ^[0-9]{3,10}$

Example:

"123456"

externalId

string

Customer-defined transaction ID. Max length: 100 characters.

Maximum string length: 100

Example:

"12312"

messageTemplate

object

Optional template details for this verification.

Show child attributes

voiceLang

string

Language code for OTP delivery (e.g., 'en-US'). Defaults to English if not provided.

Example:

"en-US"

Response

Successfully initiated verification.

status

boolean

required

Indicates whether the request was successful (true/false).

Example:

true

data

object

required

Show child attributes

​Endpoint

​Swagger

Authorizations

Body

Response

Endpoint

Swagger