Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Verifications


The Twilio Verify REST API allows you to verify that a user has a claimed device, phone number, or email address in their possession. The API lets you start a new verification for a user, and then check that the verification was successful.

Prerequisites:

  1. Create a Verification Service
  2. If you are using a Twilio Trial Account, you need to verify any non-Twilio phone numbers you wish to send SMS, Voice, or WhatsApp OTP messages.

Verification Response Properties

verification-response-properties page anchor

These fields are returned in the output JSON response. The type SID<VE> is a unique ID starting with the letters VE.

sidSID<VE>
Not PII

The unique string that we created to identify the Verification resource.

Pattern: ^VE[0-9a-fA-F]{32}$Min length: 34Max length: 34

account_sidSID<AC>

The SID of the Account(link takes you to an external page) that created the Verification resource.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34

tostring
PII MTL: 30 days

The phone number or email(link takes you to an external page) being verified. Phone numbers must be in E.164 format(link takes you to an external page).


channelenum<string>

The verification method used. One of: email(link takes you to an external page), sms, whatsapp, call, sna, or rcs.

Possible values:
smscallemailwhatsappsna

statusstring

The status of the verification. One of: pending, approved, or canceled


validboolean

Use "status" instead. Legacy property indicating whether the verification was successful.


lookupobject

Information about the phone number being verified.


amountstring

The amount of the associated PSD2 compliant transaction. Requires the PSD2 Service flag enabled.


payeestring

The payee of the associated PSD2 compliant transaction. Requires the PSD2 Service flag enabled.


send_code_attemptsarray

An array of verification attempt objects containing the channel attempted and the channel-specific transaction SID.


date_createdstring<date-time>

The date and time in GMT when the resource was created specified in RFC 2822(link takes you to an external page) format.


date_updatedstring<date-time>

The date and time in GMT when the resource was last updated specified in RFC 2822(link takes you to an external page) format.


snaobject

The set of fields used for a silent network auth (sna) verification. Contains a single field with the URL to be invoked to verify the phone number.


urlstring<uri>

The absolute URL of the Verification resource.


POST https://verify.twilio.com/v2/Services/{ServiceSid}/Verifications

To verify a user's phone number or email, start by requesting to send a verification code to their device, or use the Silent Network Auth channel to perform the verification without sending a code.

These are the available input parameters for starting a verification. The type SID<VE> is a unique ID starting with the letters VE.

Phone numbers must be in E.164 format. Learn more about how to turn phone number input into E.164 format(link takes you to an external page).

Path parameters

path-parameters page anchor
ServiceSidSID<VA>required

The SID of the verification Service(link takes you to an external page) to create the resource under.

Pattern: ^VA[0-9a-fA-F]{32}$Min length: 34Max length: 34
Tostringrequired

Channelstringrequired

The verification method to use. One of: email(link takes you to an external page), sms, whatsapp, call, sna or auto.


CustomFriendlyNamestring

A custom user defined friendly name that overwrites the existing one in the verification message


CustomMessagestring

The text of a custom message to use for the verification.


SendDigitsstring

The digits to send after a phone call is answered, for example, to dial an extension. For more information, see the Programmable Voice documentation of sendDigits(link takes you to an external page).


Localestring

Locale will automatically resolve based on phone number country code for SMS, WhatsApp, and call channel verifications. It will fallback to English or the template’s default translation if the selected translation is not available. This parameter will override the automatic locale resolution. See supported languages and more information here(link takes you to an external page).


CustomCodestring

A pre-generated code to use for verification. The code can be between 4 and 10 characters, inclusive.


Amountstring

The amount of the associated PSD2 compliant transaction. Requires the PSD2 Service flag enabled.


Payeestring

The payee of the associated PSD2 compliant transaction. Requires the PSD2 Service flag enabled.


RateLimitsobject

The custom key-value pairs of Programmable Rate Limits. Keys correspond to unique_name fields defined when creating your Rate Limit(link takes you to an external page). Associated value pairs represent values in the request that you are rate limiting on. You may include multiple Rate Limit values in each request.


ChannelConfigurationobject

email(link takes you to an external page) channel configuration in json format. The fields 'from' and 'from_name' are optional but if included the 'from' field must have a valid email address.


AppHashstring

Your App Hash(link takes you to an external page) to be appended at the end of your verification SMS body. Applies only to SMS. Example SMS body: <#> Your AppName verification code is: 1234 He42w354ol9.


TemplateSidSID<HJ>

The message template(link takes you to an external page). If provided, will override the default template for the Service. SMS and Voice channels only.

Pattern: ^HJ[0-9a-fA-F]{32}$Min length: 34Max length: 34

TemplateCustomSubstitutionsstring

A stringified JSON object in which the keys are the template's special variables and the values are the variables substitutions.


DeviceIpstring

Strongly encouraged if using the auto channel. The IP address of the client's device. If provided, it has to be a valid IPv4 or IPv6 address.


RiskCheckenum<string>

Risk_check overrides Fraud Prevention measures like Fraud Guard, Geo Permissions etc per verification attempt basis, allowing Verify to block traffic considered fraudulent if enabled or bypass active protections if disabled. Can be: enable(default) or disable. For SMS channel only.

Possible values:
enabledisable

Tagsstring

A string containing a JSON map of key value pairs of tags to be recorded as metadata for the message. The object may contain up to 10 tags. Keys and values can each be up to 128 characters in length.

Start a Verification with SMS

start-a-verification-with-sms page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.verify.v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.verifications
_11
.create({to: '+15017122661', channel: 'sms'})
_11
.then(verification => console.log(verification.sid));

Output

_23
{
_23
"sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"to": "+15017122661",
_23
"channel": "sms",
_23
"status": "pending",
_23
"valid": false,
_23
"date_created": "2015-07-30T20:00:00Z",
_23
"date_updated": "2015-07-30T20:00:00Z",
_23
"lookup": {},
_23
"amount": null,
_23
"payee": null,
_23
"send_code_attempts": [
_23
{
_23
"time": "2015-07-30T20:00:00Z",
_23
"channel": "SMS",
_23
"attempt_sid": "VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}
_23
],
_23
"sna": null,
_23
"url": "https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Verifications/VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}

Start a Verification with WhatsApp

start-a-verification-with-whatsapp page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.verify.v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.verifications
_11
.create({to: '+15017122661', channel: 'whatsapp'})
_11
.then(verification => console.log(verification.accountSid));

Output

_23
{
_23
"sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"to": "+15017122661",
_23
"channel": "whatsapp",
_23
"status": "pending",
_23
"valid": false,
_23
"date_created": "2015-07-30T20:00:00Z",
_23
"date_updated": "2015-07-30T20:00:00Z",
_23
"lookup": {},
_23
"amount": null,
_23
"payee": null,
_23
"send_code_attempts": [
_23
{
_23
"time": "2015-07-30T20:00:00Z",
_23
"channel": "whatsapp",
_23
"attempt_sid": "VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}
_23
],
_23
"sna": null,
_23
"url": "https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Verifications/VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}

Start a Verification with Voice

start-a-verification-with-voice page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.verify.v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.verifications
_11
.create({to: '+15017122661', channel: 'call'})
_11
.then(verification => console.log(verification.sid));

Output

_23
{
_23
"sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"to": "+15017122661",
_23
"channel": "call",
_23
"status": "pending",
_23
"valid": false,
_23
"date_created": "2015-07-30T20:00:00Z",
_23
"date_updated": "2015-07-30T20:00:00Z",
_23
"lookup": {},
_23
"amount": null,
_23
"payee": null,
_23
"send_code_attempts": [
_23
{
_23
"time": "2015-07-30T20:00:00Z",
_23
"channel": "SMS",
_23
"attempt_sid": "VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}
_23
],
_23
"sna": null,
_23
"url": "https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Verifications/VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}

Start a Verification with Voice to an extension

start-a-verification-with-voice-to-an-extension page anchor

Sends verification to extension 350

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.verify.v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.verifications
_15
.create({
_15
sendDigits: '350',
_15
to: '+15017122661',
_15
channel: 'call'
_15
})
_15
.then(verification => console.log(verification.sid));

Output

_23
{
_23
"sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"to": "+15017122661",
_23
"channel": "call",
_23
"status": "pending",
_23
"valid": false,
_23
"date_created": "2015-07-30T20:00:00Z",
_23
"date_updated": "2015-07-30T20:00:00Z",
_23
"lookup": {},
_23
"amount": null,
_23
"payee": null,
_23
"send_code_attempts": [
_23
{
_23
"time": "2015-07-30T20:00:00Z",
_23
"channel": "SMS",
_23
"attempt_sid": "VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}
_23
],
_23
"sna": null,
_23
"url": "https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Verifications/VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}


Start New Verification With Silent Network Auth

start-new-verification-with-silent-network-auth page anchor
(information)

Info

Verify Silent Network Auth (SNA) is currently in the beta release stage, talk to an expert(link takes you to an external page) to request access to this feature.

Silent Network Auth (SNA) is a secure verification channel that verifies user possession of a mobile number without explicit user intervention by using its built-in connectivity to the mobile network operator (carrier). In the background, Twilio verifies the phone number by confirming directly from the carrier that the number corresponds to the SIM card located in the device requesting the authentication. This all happens without one-time password prompts or visible redirects for the end-user.

See Verify Silent Network Auth Overview for more information on this exciting feature.

It takes three steps to use SNA:

  1. Start a new Verification with the sna channel using Verifications API.
  2. Send POST request to response property sna.url from client device that is connected to a mobile network.
  3. Check that the Verification was successful using Verification Check API .

To begin, use the Start New Verification endpoint with the parameter channel=sna.

Start a Verification With Silent Network Auth

start-a-verification-with-silent-network-auth page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.verify.v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.verifications
_11
.create({to: '+15017122661', channel: 'sna'})
_11
.then(verification => console.log(verification.sid));

Output

_33
{
_33
"sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"to": "+15017122661",
_33
"channel": "sna",
_33
"status": "pending",
_33
"valid": false,
_33
"date_created": "2015-07-30T20:00:00Z",
_33
"date_updated": "2015-07-30T20:00:00Z",
_33
"lookup": {
_33
"carrier": {
_33
"mobile_country_code": "311",
_33
"type": "mobile",
_33
"error_code": null,
_33
"mobile_network_code": "180",
_33
"name": "T-Mobile USA, Inc."
_33
}
_33
},
_33
"amount": null,
_33
"payee": null,
_33
"send_code_attempts": [
_33
{
_33
"time": "2015-07-30T20:00:00Z",
_33
"channel": "sna",
_33
"attempt_sid": "VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_33
}
_33
],
_33
"sna": {
_33
"url": "https://mi.dnlsrv.com/m/id/ANBByzx7?data=AAAglRRdNn02iTFWfDWwdTjOzM8o%2F6JB86fH%2Bt%2FFftUPj0pFA0u8%2FibWuYwzmMeMOtdTwYlsO8V%2FXF%2BJmngMhbeGKYhHeTOF2H9VrGEYKcEEklPxHgb5GgL3XtYa33j3lIU%2By6InvoV%2FowWHBzA0QeFPBh6vmJ8LoUPJqGE7q0PRz618Z4ym1AGq%2BaomSq9PlP4rCduv9Cmtxu%2FrvPSBwocs0GCWDE8seK8t9epmPQW7gwODxkAiKr9UxhJd9KvmBVuAQPf%2BoFQVo86USXkhXqTvUzB2bNUYY9FCy3CWgZFTOa1D3H1CVxf1eHzYIswNA7SmOzP%2FBX8g6%2B0hkzwMRkcit3gBNs4evAVJiqAgYvUlrtGwwv9bFx4X7jWSHY4%3D&cipherSalt=yANeDq09bwM38SJs"
_33
},
_33
"url": "https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Verifications/VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_33
}

Send POST request to response property sna.url

send-post-request-to-response-property-snaurl page anchor

Check your response from the Start New Verification endpoint for the sna.url property:


_10
"sna": {
_10
"url": "https://mi.dnlsrv.com/m/id/ANBByzx7?data=AAAglRRdNn02iTFWfDWwdTjOzM8o%2F6JB86fH%2Bt%2FFftUPj0pFA0u8%2FibWuYwzmMeMOtdTwYlsO8V%2FXF%2BJmngMhbeGKYhHeTOF2H9VrGEYKcEEklPxHgb5GgL3XtYa33j3lIU%2By6InvoV%2FowWHBzA0QeFPBh6vmJ8LoUPJqGE7q0PRz618Z4ym1AGq%2BaomSq9PlP4rCduv9Cmtxu%2FrvPSBwocs0GCWDE8seK8t9epmPQW7gwODxkAiKr9UxhJd9KvmBVuAQPf%2BoFQVo86USXkhXqTvUzB2bNUYY9FCy3CWgZFTOa1D3H1CVxf1eHzYIswNA7SmOzP%2FBX8g6%2B0hkzwMRkcit3gBNs4evAVJiqAgYvUlrtGwwv9bFx4X7jWSHY4%3D&cipherSalt=yANeDq09bwM38SJs"
_10
}

Then do an HTTP POST request to sna.url over the end user's mobile network to continue the authentication process. Note that sna.url is unique for every Verification Attempt, has a defined time-to-live of 10 minutes, and can only be processed once.


_10
curl -X POST https://mi.dnlsrv.com/m/id/ANBByzx7?data=AAAglRRdNn02iTFWfDWwdTjOzM8o%2F6JB86fH%2Bt%2FFftUPj0pFA0u8%2FibWuYwzmMeMOtdTwYlsO8V%2FXF%2BJmngMhbeGKYhHeTOF2H9VrGEYKcEEklPxHgb5GgL3XtYa33j3lIU%2By6InvoV%2FowWHBzA0QeFPBh6vmJ8LoUPJqGE7q0PRz618Z4ym1AGq%2BaomSq9PlP4rCduv9Cmtxu%2FrvPSBwocs0GCWDE8seK8t9epmPQW7gwODxkAiKr9UxhJd9KvmBVuAQPf%2BoFQVo86USXkhXqTvUzB2bNUYY9FCy3CWgZFTOa1D3H1CVxf1eHzYIswNA7SmOzP%2FBX8g6%2B0hkzwMRkcit3gBNs4evAVJiqAgYvUlrtGwwv9bFx4X7jWSHY4%3D&cipherSalt=yANeDq09bwM38SJs

This POST request will prompt multiple redirects behind the scenes, including contacting the carrier to confirm phone number ownership. You can expect to receive a 200 response from this request in under four seconds.

Next, use Verification Check API to confirm that the POST request and Verification Attempt was successful.


Start New Verification With Automatic Channel Selection

start-new-verification-with-automatic-channel-selection page anchor
(information)

Info

Verify Automatic Channel Selection is currently in the Pilot maturity stage, please contact sales(link takes you to an external page) to request access to this feature.

Automatic Channel Selection is a verification channel that attempts to verify with Silent Network Auth (SNA) and uses SMS as a fallback if needed. Read more about Automatic Channel Selection here.

Take the following steps to use Automatic Channel Selection:

  1. Start a new Verification with the auto channel using Verifications API, including the optional parameter device_ip .
  2. Check the response for the channel property to see if sna or sms was used.
  3. Check that the Verification was successful using Verification Check API .

Start a Verification With Automatic Channel Detection

start-a-verification-with-automatic-channel-detection page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.verify.v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.verifications
_15
.create({
_15
deviceIp: '0.000.00.000',
_15
to: '+15017122661',
_15
channel: 'auto'
_15
})
_15
.then(verification => console.log(verification.sid));

Output

_33
{
_33
"sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33
"to": "+15017122661",
_33
"channel": "auto",
_33
"status": "pending",
_33
"valid": false,
_33
"date_created": "2015-07-30T20:00:00Z",
_33
"date_updated": "2015-07-30T20:00:00Z",
_33
"lookup": {
_33
"carrier": {
_33
"mobile_country_code": "311",
_33
"type": "mobile",
_33
"error_code": null,
_33
"mobile_network_code": "180",
_33
"name": "T-Mobile USA, Inc."
_33
}
_33
},
_33
"amount": null,
_33
"payee": null,
_33
"send_code_attempts": [
_33
{
_33
"time": "2015-07-30T20:00:00Z",
_33
"channel": "sna",
_33
"attempt_sid": "VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_33
}
_33
],
_33
"sna": {
_33
"url": "https://mi.dnlsrv.com/m/id/ANBByzx7?data=AAAglRRdNn02iTFWfDWwdTjOzM8o%2F6JB86fH%2Bt%2FFftUPj0pFA0u8%2FibWuYwzmMeMOtdTwYlsO8V%2FXF%2BJmngMhbeGKYhHeTOF2H9VrGEYKcEEklPxHgb5GgL3XtYa33j3lIU%2By6InvoV%2FowWHBzA0QeFPBh6vmJ8LoUPJqGE7q0PRz618Z4ym1AGq%2BaomSq9PlP4rCduv9Cmtxu%2FrvPSBwocs0GCWDE8seK8t9epmPQW7gwODxkAiKr9UxhJd9KvmBVuAQPf%2BoFQVo86USXkhXqTvUzB2bNUYY9FCy3CWgZFTOa1D3H1CVxf1eHzYIswNA7SmOzP%2FBX8g6%2B0hkzwMRkcit3gBNs4evAVJiqAgYvUlrtGwwv9bFx4X7jWSHY4%3D&cipherSalt=yANeDq09bwM38SJs"
_33
},
_33
"url": "https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Verifications/VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_33
}


Start New Verification With a Predefined Template

start-new-verification-with-a-predefined-template page anchor

The message body of an SMS or Voice Verification can be overridden by using a template. To do so, the template SID<HJ> must be sent as a parameter in the Start Verification request.
The template SID<HJ> is a unique ID starting with the letters HJ. A complete list of the available templates for the account can be obtained by querying the Templates API.

Start a Verification using a template

start-a-verification-using-a-template page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.verify.v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.verifications
_15
.create({
_15
templateSid: 'HJXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
_15
to: '+15017122661',
_15
channel: 'sms'
_15
})
_15
.then(verification => console.log(verification.status));

Output

_23
{
_23
"sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"to": "+15017122661",
_23
"channel": "sms",
_23
"status": "pending",
_23
"valid": false,
_23
"date_created": "2015-07-30T20:00:00Z",
_23
"date_updated": "2015-07-30T20:00:00Z",
_23
"lookup": {},
_23
"amount": null,
_23
"payee": null,
_23
"send_code_attempts": [
_23
{
_23
"time": "2015-07-30T20:00:00Z",
_23
"channel": "SMS",
_23
"attempt_sid": "VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}
_23
],
_23
"sna": null,
_23
"url": "https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Verifications/VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}

Start a Verification with Email

start-a-verification-with-email page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.verify.v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.verifications
_11
.create({to: 'customer@example.com', channel: 'email'})
_11
.then(verification => console.log(verification.sid));

Output

_23
{
_23
"sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"to": "customer@example.com",
_23
"channel": "email",
_23
"status": "pending",
_23
"valid": false,
_23
"date_created": "2015-07-30T20:00:00Z",
_23
"date_updated": "2015-07-30T20:00:00Z",
_23
"lookup": {},
_23
"amount": null,
_23
"payee": null,
_23
"send_code_attempts": [
_23
{
_23
"time": "2015-07-30T20:00:00Z",
_23
"channel": "SMS",
_23
"attempt_sid": "VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}
_23
],
_23
"sna": null,
_23
"url": "https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Verifications/VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}

Email Channel Configuration

email-channel-configuration page anchor
(information)

Info

Verify's email channel requires additional Service configuration. Please refer to the email channel setup documentation for detailed instructions.

The email ChannelConfiguration parameter is an object that supports the following keys:

KeyData TypeDescription
fromstringOptional parameter. If included must be a valid email address.
from_namestringOptional parameter. Name of the sender.
template_idstringOverride the default template from the Verify Service email integration. Create a new template in the SendGrid dashboard(link takes you to an external page) or learn more in the SendGrid docs(link takes you to an external page).
substitutionsobjectVariable substitution for dynamic email templates (learn more(link takes you to an external page)). See code sample below.

Substitutions code sample

substitutions-code-sample page anchor

_10
{
_10
"substitutions": {
_10
"username": "jdoe321",
_10
"first_name": "Jane",
_10
"last_name": "Doe"
_10
}
_10
}

Localization and Supported Languages

localization-and-supported-languages page anchor

Verify supports delivering verification codes in more than 30 languages over SMS, Voice and WhatsApp. A verification message's language will automatically resolve based on the country code of the phone number provided, with English as the fallback language. To find out more about which languages are supported visit our page on Supported Languages.

(information)

Canadian Carrier Data Support

By default, Verify will not return carrier data for Canadian phone numbers. If you need carrier data on Canadian phone numbers, please visit our support site(link takes you to an external page) to enable this feature.


GET https://verify.twilio.com/v2/Services/{ServiceSid}/Verifications/{Sid}

ServiceSidSID<VA>required

The SID of the verification Service(link takes you to an external page) to fetch the resource from.

Pattern: ^VA[0-9a-fA-F]{32}$Min length: 34Max length: 34

Sidstringrequired

The Twilio-provided string that uniquely identifies the Verification resource to fetch.

Fetch a Verification by SID

fetch-a-verification-by-sid page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.verify.v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.verifications('VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.fetch()
_11
.then(verification => console.log(verification.status));

Output

_23
{
_23
"sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"to": "+15017122661",
_23
"channel": "sms",
_23
"status": "pending",
_23
"valid": false,
_23
"date_created": "2015-07-30T20:00:00Z",
_23
"date_updated": "2015-07-30T20:00:00Z",
_23
"lookup": {},
_23
"amount": null,
_23
"payee": null,
_23
"send_code_attempts": [
_23
{
_23
"time": "2015-07-30T20:00:00Z",
_23
"channel": "SMS",
_23
"attempt_sid": "VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}
_23
],
_23
"sna": null,
_23
"url": "https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Verifications/VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}


Update a Verification Status

update-a-verification-status page anchor
POST https://verify.twilio.com/v2/Services/{ServiceSid}/Verifications/{Sid}

Mark the verification as approved after your application had validated the verification code.

Mark the verification as canceled to start a new verification session with a different code before the previous code expires (10 minutes). Only recommended during testing(link takes you to an external page) or if you're using custom verification codes.

For most other use cases, Verify is able to manage the complete lifecycle of a verification with the Verification Check Resource.

ServiceSidSID<VA>required

The SID of the verification Service(link takes you to an external page) to update the resource from.

Pattern: ^VA[0-9a-fA-F]{32}$Min length: 34Max length: 34

Sidstringrequired

The Twilio-provided string that uniquely identifies the Verification resource to update.

Statusenum<string>required

The new status of the resource. Can be: canceled or approved.

Possible values:
canceledapproved

Manually Approve Verification using SID

manually-approve-verification-using-sid page anchor

Only use if using Custom Verification Codes

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.verify.v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.verifications('VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.update({status: 'approved'})
_11
.then(verification => console.log(verification.status));

Output

_23
{
_23
"sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"to": "+15017122661",
_23
"channel": "sms",
_23
"status": "approved",
_23
"valid": false,
_23
"date_created": "2015-07-30T20:00:00Z",
_23
"date_updated": "2015-07-30T20:00:00Z",
_23
"lookup": {},
_23
"amount": null,
_23
"payee": null,
_23
"send_code_attempts": [
_23
{
_23
"time": "2015-07-30T20:00:00Z",
_23
"channel": "SMS",
_23
"attempt_sid": "VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}
_23
],
_23
"sna": null,
_23
"url": "https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Verifications/VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}

Manually Approve Verification using Phone Number

manually-approve-verification-using-phone-number page anchor

Only use if using Custom Verification Codes

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.verify.v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.verifications('+15017122661')
_11
.update({status: 'approved'})
_11
.then(verification => console.log(verification.status));

Output

_23
{
_23
"sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"to": "+15017122661",
_23
"channel": "sms",
_23
"status": "approved",
_23
"valid": true,
_23
"date_created": "2015-07-30T20:00:00Z",
_23
"date_updated": "2015-07-30T20:00:00Z",
_23
"lookup": {},
_23
"amount": null,
_23
"payee": null,
_23
"send_code_attempts": [
_23
{
_23
"time": "2015-07-30T20:00:00Z",
_23
"channel": "SMS",
_23
"attempt_sid": "VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}
_23
],
_23
"sna": null,
_23
"url": "https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Verifications/VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}

Manually Cancel a Verification

manually-cancel-a-verification page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_11
// Download the helper library from https://www.twilio.com/docs/node/install
_11
// Find your Account SID and Auth Token at twilio.com/console
_11
// and set the environment variables. See http://twil.io/secure
_11
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11
const authToken = process.env.TWILIO_AUTH_TOKEN;
_11
const client = require('twilio')(accountSid, authToken);
_11
_11
client.verify.v2.services('VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.verifications('VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_11
.update({status: 'canceled'})
_11
.then(verification => console.log(verification.status));

Output

_23
{
_23
"sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_23
"to": "+15017122661",
_23
"channel": "sms",
_23
"status": "canceled",
_23
"valid": false,
_23
"date_created": "2015-07-30T20:00:00Z",
_23
"date_updated": "2015-07-30T20:00:00Z",
_23
"lookup": {},
_23
"amount": null,
_23
"payee": null,
_23
"send_code_attempts": [
_23
{
_23
"time": "2015-07-30T20:00:00Z",
_23
"channel": "SMS",
_23
"attempt_sid": "VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}
_23
],
_23
"sna": null,
_23
"url": "https://verify.twilio.com/v2/Services/VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Verifications/VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_23
}


Now that you know how to start a verfication, you can use the Verification Check API to validate if the code a user provided was correct or that the Silent Network Auth process was successful.


Rate this page: