Verify API - Specify Verify API template

📘
NOTE:
To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

This page explains step-by-step how to specify a Verify API template. A template is declared once for the entire verification process and it is available for use on all channels. If a template isn't specified, Verify API will use a default template.

📘
NOTE:
You must use the same template name for each of your active channels (for example, WhatsApp, Viber, Email, SMS) if you are utilizing a fallback channel.

Before you begin

Set up a template for Verify API. Contact Telesign Customer Support or your Telesign contact to create this template.

Specify a Verify API template

Send a Create a verification process request to the Verify API. Include the following param values:

Parameter	Value	Description	Required?
`recipient.phone_number`	Digits without spaces or special characters, beginning with the country dialing code.	The recipient's phone number	Yes
`recipient.email`	A valid email address.	The recipient's email address.	Yes, if the primary verification method is email.
`message_template.name`	lowercase alpha characters and underscores.	The name of your template.	Yes
`verification_policy[0].method`	`sms,` whatsapp`,` viber`,` rcs`, or` email`.	One of the verification methods included in a verification policy.	Required only if a channel is not already defined as the primary verification method for this account's default verification policy.
`verification_policy[0].fallback_time`	A time in seconds.	The time window in seconds that the service waits before abandoning the current verification method and then initiating verification using the next method.	No, but recommended in case your recipient cannot be reached using the primary verification channel.
`verification_policy[1].method`	`sms`	One of the verification methods included in a verification policy. This is your backup method.	No, but recommended in case your recipient cannot be reached using the primary verification channel.
`security_factor`	A numeric code, formatted as a string.	The OTP to include in the message to the end user.	No. Can be used if you wish to define your own OTP instead of allowing Telesign to generate an OTP.

The service then sends a message using the primary channel you selected to your end user, inserting a randomly generated OTP in the message. (See the appropriate channel-specific guide page for more information.)
Save the value of the property reference_id from the response. You will need it to complete the verification flow.
The status.code and status.description properties in the response indicate the preliminary delivery status of the SMS.
Follow the steps for Complete verification and get delivery status on the appropriate channel-specific guide page.

📘
NOTE:
Updating a verification process using the procedure explained in Complete verification and get delivery status is a mandatory step when using Verify API. This step allows Telesign to know the real state of your verification as well as control all the features related to a verification process such as fallback, callback, and pricing. If your end user has verified themselves but the verification process is not updated, these features might not work as intended and you can be billed incorrectly.

Successful request

This is an example of a successful request using a message template named verification_template that was previously set up.

curl --request POST \
     --url https://verify.telesign.com/verification \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "recipient": {
    "phone_number": "11234567890"
  },
  "message_template": {
    "name": "verification_template"
  },
  "security_factor": "123456",
  "verification_policy": [
    {
      "method": "viber",
      "fallback_time":60
    },
    {
      "method": "rcs",
      "fallback_time":120
    }
  ]
}

Successful response

This is a successful response returned after a successful attempt with the correct template name.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "mobile_app_token": "b7591bc3bd874f6085ec300ccec02462",
  "recipient": {
    "phone_number": "11234567890"
  },
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "state": "CREATED",
  "status": {
    "code": 3901,
    "description": "Request in progress"
  }
}

📘
NOTE:
The status.code property gives you status of delivery to the destination carrier, not necessarily all the way to the end-user.

Unsuccessful request

In this example, the wrong template name, verify_template, instead of verification_template, is used.

curl --request POST \
     --url https://verify.telesign.com/verification \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "recipient": {
    "phone_number": "11234567890"
  },
  "message_template": {
    "name": "verify_template"
  },
  "security_factor": "123456",
  "verification_policy": [
    {
      "method": "viber",
      "fallback_time":60
    },
    {
      "method": "rcs",
      "fallback_time":120
    }
  ]
}

Unsuccessful response

This is an unsuccessful response returned after an attempt using the wrong template name.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "mobile_app_token": "948861fb5d0446ad9475d18d8a59c6e6",
  "recipient": {
    "phone_number": "11234567890"
  },
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "state": "CREATED",
  "status": {
    "code": 3901,
    "description": "Request in progress"
  }
}

Unsuccessful callback example or GET example

When you have callbacks or delivery reports (DLRs) enabled, an unsuccessful request or an unsuccessful GET results in additional details including the reason for the failure provided to you. In this case, the callback notes that "Specified template does not exist for selected channel".

curl --request POST \
     --url https://your-callback-url.com/verify_dlr_endpoint \
     --header 'content-type: application/json' \
     --data '
{
  "created_on": "2024-09-02T13:10:21.328000Z",
  "inner_methods": [
    {
      "err_code": 3112,
      "err_msg": "Specified template does not exist for selected channel",
      "expires_on": "2024-09-02T13:11:21.339000Z",
      "method": "viber",
      "state": "FAILED",
      "tried_on": 1725282621339,
      "updated_on": "2024-09-02T13:10:21.356545Z"
    },
    {
      "err_code": 3112,
      "err_msg": "Specified template does not exist for selected channel",
      "expires_on": "2024-09-02T13:15:21.360000Z",
      "method": "rcs",
      "state": "FAILED",
      "tried_on": 1725282621360,
      "updated_on": "2024-09-02T13:10:21.000000Z"
    }
  ],
  "push_registration": false,
  "recipient": {
    "phone_number": "11234567890"
  },
  "reference_id": "0123456789ABCDEF0123456789ABCDEF",
  "state": "FAILED",
  "updated_on": "2024-09-02T13:10:21.401000Z",
  "verification_policy": [
    {
      "fallback_time": 60,
      "method": "viber"
    },
    {
      "fallback_time": 300,
      "method": "rcs"
    }
  ]
}

Verify API - Specify Verify API template

📘
NOTE:

📘
NOTE:

Before you begin

Specify a Verify API template

📘
NOTE:

Successful request

Successful response

📘
NOTE:

Unsuccessful request

Unsuccessful response

Unsuccessful callback example or GET example

📘NOTE:

📘NOTE:

Before you begin

Specify a Verify API template

📘NOTE:

Successful request

Successful response

📘NOTE:

Unsuccessful request

Unsuccessful response

Unsuccessful callback example or GET example

📘
NOTE:

📘
NOTE:

📘
NOTE:

📘
NOTE: