Verify API
As part of Twilio's account security offerings, the Twilio Verify API makes it simple to add user verification to your web application. The API supports the following channels:
- SMS
- Passkeys
- Silent Network Auth
- Automatic Channel Selection
- Voice
- TOTP (authenticator apps like Authy and Google Authenticator)
- Push and Silent Device Approval
For more information on Verify, see our product page.
All URLs referenced in the documentation have the following base:
https://verify.twilio.com/v2/
The Twilio REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.
To authenticate requests to the Twilio APIs, Twilio supports HTTP Basic authentication. Use your API key as the username and your API key secret as the password. You can create an API key either in the Twilio Console or using the API.
Note: Twilio doesn't recommend using your Account SID and Auth Token in production. For local testing, you can use your Account SID as the username and your Auth token as the password. You can find your Account SID and Auth Token in the Twilio Console.
Learn more about Twilio API authentication.
1curl -X POST https://verify.twilio.com/v2/Services \2-d FriendlyName=MyServiceName \3-u $TWILIO_API_KEY:$TWILIO_API_KEY_SECRET
This guide shows the 3 steps to completing a basic one-time passcode (OTP) verification. Follow the links for more documentation on advanced features such as service configuration, custom codes, rate limiting, PSD2 compliance, and more.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createService() {11const service = await client.verify.v2.services.create({12friendlyName: "My First Verify Service",13});1415console.log(service.sid);16}1718createService();
Response
1{2"sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"friendly_name": "My First Verify Service",5"code_length": 4,6"lookup_enabled": false,7"psd2_enabled": false,8"skip_sms_to_landlines": false,9"dtmf_input_required": false,10"tts_name": "name",11"mailer_sid": "MDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",12"do_not_share_warning_enabled": false,13"custom_code_enabled": true,14"push": {15"include_date": false,16"apn_credential_sid": "CRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",17"fcm_credential_sid": null18},19"totp": {20"issuer": "test-issuer",21"time_step": 30,22"code_length": 3,23"skew": 224},25"whatsapp": {26"msg_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",27"from": "whatsapp:+1234567890"28},29"default_template_sid": "HJaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",30"verify_event_subscription_enabled": false,31"date_created": "2015-07-30T20:00:00Z",32"date_updated": "2015-07-30T20:00:00Z",33"url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",34"links": {35"verification_checks": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/VerificationCheck",36"verifications": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Verifications",37"rate_limits": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RateLimits",38"messaging_configurations": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/MessagingConfigurations",39"entities": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities",40"webhooks": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks",41"access_tokens": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AccessTokens"42}43}
Create a Service in one of two ways:
- In the Twilio Verify Console
- Using the API (code sample on this page)
A Verification Service is the set of common configurations used to create and check verifications. This includes features like:
- Friendly Name (used in the Verification message templates, except in countries with brand restrictions)
- Code Length
- ...and more
One verification service can be used to send multiple verification tokens, it is not necessary to create a new service each time.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createVerification() {11const verification = await client.verify.v212.services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.verifications.create({14channel: "sms",15to: "+15017122661",16});1718console.log(verification.status);19}2021createVerification();
Response
1{2"sid": "VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"to": "+15017122661",6"channel": "sms",7"status": "pending",8"valid": false,9"date_created": "2015-07-30T20:00:00Z",10"date_updated": "2015-07-30T20:00:00Z",11"lookup": {},12"amount": null,13"payee": null,14"send_code_attempts": [15{16"time": "2015-07-30T20:00:00Z",17"channel": "SMS",18"attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"19}20],21"sna": null,22"url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Verifications/VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"23}
This will send a token to the end user through the specified channel. Newly created verifications will show a status of pending
. Supported channels are:
sms
, see the Verify SMS Overviewcall
email
, checkout the guide Send Email Verifications with Verify and Twilio SendGridwhatsapp
, see the Verify WhatsApp Overview
Learn more about how to turn phone number input into E.164 format or how to customize the verification message.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createVerificationCheck() {11const verificationCheck = await client.verify.v212.services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")13.verificationChecks.create({14code: "123456",15to: "+15017122661",16});1718console.log(verificationCheck.status);19}2021createVerificationCheck();
Response
1{2"sid": "VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",3"service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",4"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",5"to": "+15017122661",6"channel": "sms",7"status": "approved",8"valid": true,9"amount": null,10"payee": null,11"sna_attempts_error_codes": [],12"date_created": "2015-07-30T20:00:00Z",13"date_updated": "2015-07-30T20:00:00Z"14}
This will check whether the user-provided token is correct.
Token | Status in response |
---|---|
Correct | approved |
Incorrect | pending |
VerificationCheck documentation.
Info
You made it through the Verify API Overview. To protect your service against fraud, view our guidance on Preventing Toll Fraud when using Verify.