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.
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.
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.
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.
The custom key-value pairs of Programmable Rate Limits. Keys correspond to unique_name fields defined when creating your Rate Limit. Associated value pairs represent values in the request that you are rate limiting on. You may include multiple Rate Limit values in each request.
email 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.
Your App Hash 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.
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.
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
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_21
// Download the helper library from https://www.twilio.com/docs/node/install
_21
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_21
_21
// Find your Account SID and Auth Token at twilio.com/console
_21
// and set the environment variables. See http://twil.io/secure
Verify Silent Network Auth (SNA) is currently in the beta release stage, talk to an expert 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.
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
(information)
Info
Verify Automatic Channel Selection is currently in the Pilot maturity stage, please contact sales to request access to this feature.
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
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl
_22
// Download the helper library from https://www.twilio.com/docs/node/install
_22
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_22
_22
// Find your Account SID and Auth Token at twilio.com/console
_22
// and set the environment variables. See http://twil.io/secure
The email ChannelConfiguration parameter is an object that supports the following keys:
Key
Data Type
Description
from
string
Optional parameter. If included must be a valid email address.
from_name
string
Optional parameter. Name of the sender.
template_id
string
Override the default template from the Verify Service email integration. Create a new template in the SendGrid dashboard or learn more in the SendGrid docs.
substitutions
object
Variable substitution for dynamic email templates (learn more). See code sample below.
Substitutions code sample
_10
{
_10
"substitutions": {
_10
"username": "jdoe321",
_10
"first_name": "Jane",
_10
"last_name": "Doe"
_10
}
_10
}
Localization and Supported Languages
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 to enable this feature.
Fetch a Verification
GET https://verify.twilio.com/v2/Services/{ServiceSid}/Verifications/{Sid}
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 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.
Now that you know how to start a verification, 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.