Create a verification process

post

https://verify.telesign.com/verification

🚧
CAUTION:
As part of our ongoing platform improvements and the migration to a new supporting platform, the Push Verify functionality is temporarily unavailable. This notice will be removed once Push Verify becomes available again.
Other Verify API SDK capabilities, including QR Verify and Silent Verify, are not impacted.

Use this action to create a verification process for the specified phone number.

📘
NOTE:
Updating a verification process using the procedure explained in each channel's Complete verification and get delivery status section on its Get Started page 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 which can lead to extra costs or incorrect billing.

General requirements

Authentication: Basic (easiest to implement) or Digest
Encoding: Accepts only UTF-8 unicode characters as inputs.
Accepts: application/json
Responds with: application/json
Required headers: Content-Type - application/json
Rate limit: Default rate limits by product

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Payload for creating a verification process.

recipient

object

required

Contains properties with the recipient identifier for a verification process.

security_factor

string

length between 3 and 10

A one-time passcode (OTP) to use for this verification process, for all OTP methods. By default, Telesign randomly generates a six-digit numeric OTP for you and inserts it into messages to your end users. You can override the default behavior by including your own OTP here. Only numeric characters are supported. Contact Telesign Customer Support to change the required OTP length configured for your account.

verification_policy

array of objects

length ≥ 1

An ordered set of verification methods and their fallback times that the Verify API uses for this verification process. See verification policy for more details.

Verification Policy

method

string

enum

One of the verification methods included in a verification policy. Each method employs a Telesign service, such as Silent Verify or Push Verify.

Allowed:

fallback_time

integer

≥ 30

The time window in seconds that the service waits before abandoning the current verification method and then initiating verification using the next method specified in the active verification policy. It is possible for the failover to happen earlier if certain failure conditions occur.

device_registration

string

This verification process is for the purpose of registering a device for Push Verify. See Verify API - Register a new device with Push Verify for further context on when to use this. When used with Push Verify, the value of this parameter is stamp.

external_id

string

length ≤ 100

A customer-generated ID for this transaction. The response simply echoes the value provided for this parameter.

message_template

object

Contains properties related to the template set up for use with Verify API.

voice_lang

string

A supported language code specifying the language the service will use when delivering the OTP message. If a code isn't provided, the default language, English (en-US), is used to deliver the OTP message.

Responses

Status.code	Status.Description	Additional details
3901	Request in progress	Telesign has created this verification process and it is ready to use. (Intermediate)

Status.code	Status.Description	Additional details
3101	Invalid value for parameter phone_number: {phone_number}	Phone number is too long, too short, or contains non-digit values.
3103	Unsupported value for parameter external_id	External ID is longer than 100 characters or contains non-ASCII characters.
3110	Invalid request	The API request or its JSON payload is improperly formatted.
3302	Missing parameter phone_number	The API request does not contain the mandatory parameter `phone_number`.

Status.code	Status.Description	Additional details
3203	Callback URL parameter not enabled for Customer ID	Using callback_url in the API request is not allowed for this account.
3400	Not authorized	No permissions for this resource or authorization failed.
3906	Unified Verification Product not enabled for Customer ID	This product is not enabled for this account.

Status.code	Status.Description	Additional details
3116	Payload limit size exceeded	The payload of this request exceeds the 10KB limit.

Status.code	Status.Description	Additional details
3500	System Unavailable	The system is currently unavailable. You should resubmit this request.

Language

Credentials

Basic

base64

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Success. Your verification request has been accepted and the verification process with this end user has been created accordingly. Status.codeStatus.DescriptionAdditional details3901Request in progressTelesign has created this verification process and it is ready to use. (Intermediate)