Menu

Expand
Rate 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

Verification Response Properties

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

Resource Properties in REST API format
sid
sid<VE> Not PII

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

service_sid
sid<VA> Not PII

The SID of the Service the resource is associated with.

account_sid
sid<AC> Not PII

The SID of the Account that created the Verification resource.

to

The phone number or email being verified. Phone numbers must be in E.164 format.

channel
enum:channel Not PII

The verification method used. One of: email, sms, whatsapp, call, or sna.

status
string Not PII

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

valid
boolean Not PII

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

lookup
object Not PII

Information about the phone number being verified.

amount

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

payee

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

send_code_attempts
object[] Not PII

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

date_created
date_time<iso8601> Not PII

The date and time in GMT when the resource was created specified in RFC 2822 format.

date_updated
date_time<iso8601> Not PII

The date and time in GMT when the resource was last updated specified in RFC 2822 format.

sna
object Not PII

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.

url
url Not PII

The absolute URL of the Verification resource.

Start New Verification

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.

Parameters
Parameters in REST API format
service_sid
Path
post sid<VA> Not PII

The SID of the verification Service to create the resource under.

to
Required
post string PII MTL: 30 DAYS

The phone number or email to verify. Phone numbers must be in E.164 format.

channel
Required
post string Not PII

The verification method to use. One of: email, sms, whatsapp, call, or sna.

custom_friendly_name
Optional
post string Not PII

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

send_digits
Optional
post string Not PII

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
Optional
post string Not PII

Locale will automatically resolve based on phone number country code for SMS, WhatsApp and call channel verifications. This parameter will override the automatic locale. See supported languages and more information here..

custom_code
Optional
post string Not PII

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

amount
Optional
post string PII MTL: 1 DAYS

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

payee
Optional
post string PII MTL: 1 DAYS

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

rate_limits
Optional
post object Not PII

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.

channel_configuration
Optional
post object Not PII

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.

app_hash
Optional
post string Not PII

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.

template_sid
Optional
post sid<HJ> Not PII

The message template. If provided, will override the default template for the Service. SMS channel only.

template_custom_substitutions
Optional
post string Not PII

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

Example 1
        
        
        
        Example 2
              
              
              
              Example 3
                    
                    
                    
                    Example 4
                          
                          
                          
                          Sends verification to extension 350

                          Start a Verification with Voice to an extension

                          Sends verification to extension 350
                          Example 5
                                
                                
                                

                                Start New Verification With Silent Network Auth

                                Verify Silent Network Auth is currently in the Pilot maturity stage, please contact sales 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.

                                Send POST request to response property sna.url

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

                                "sna": {
                                     "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"
                                }

                                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.

                                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.

                                Example 6
                                      
                                      
                                      

                                      Email Channel Configuration

                                      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:

                                      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). i.e.

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

                                      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.

                                      Canadian Carrier Data Support

                                      By default, Verify will not return carrier data for Candian 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}
                                      Parameters
                                      Parameters in REST API format
                                      service_sid
                                      Path
                                      get sid<VA> Not PII

                                      The SID of the verification Service to fetch the resource from.

                                      sid
                                      Path
                                      get string Not PII

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

                                      Example 1
                                            
                                            
                                            

                                            Update a Verification Status

                                            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.

                                            Parameters
                                            Parameters in REST API format
                                            service_sid
                                            Path
                                            post sid<VA> Not PII

                                            The SID of the verification Service to update the resource from.

                                            sid
                                            Path
                                            post string Not PII

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

                                            status
                                            Required
                                            post ienum:status Not PII

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

                                            Example 1
                                                  
                                                  
                                                  
                                                  Only use if using Custom Verification Codes

                                                  Manually Approve Verification using SID

                                                  Only use if using Custom Verification Codes
                                                  Example 2
                                                        
                                                        
                                                        
                                                        Only use if using Custom Verification Codes

                                                        Manually Approve Verification using Phone Number

                                                        Only use if using Custom Verification Codes
                                                        Example 3
                                                              
                                                              
                                                              

                                                              Next: Check a Verification

                                                              Validate if the code a user provided was correct or that the Silent Network Auth process was successful with the Verification Check API.

                                                              Rate this page:

                                                              Need some help?

                                                              We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                                                                    
                                                                    
                                                                    

                                                                    Thank you for your feedback!

                                                                    Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                                                    Sending your feedback...
                                                                    🎉 Thank you for your feedback!
                                                                    Something went wrong. Please try again.

                                                                    Thanks for your feedback!

                                                                    Refer us and get $10 in 3 simple steps!

                                                                    Step 1

                                                                    Get link

                                                                    Get a free personal referral link here

                                                                    Step 2

                                                                    Give $10

                                                                    Your user signs up and upgrade using link

                                                                    Step 3

                                                                    Get $10

                                                                    1,250 free SMSes
                                                                    OR 1,000 free voice mins
                                                                    OR 12,000 chats
                                                                    OR more