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
WhatsApp
Email
TOTP (authenticator apps like Authy and Google Authenticator)
Push and Silent Device Approval

For more information on Verify, see our product page.

Base URL

All URLs referenced in the documentation have the following base:


_10https://verify.twilio.com/v2/

The Twilio REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

Authentication

HTTP requests to the REST API are protected with HTTP Basic authentication. To learn more about how Twilio handles authentication, please refer to our security documentation. In short, you will use your Twilio account SID as the username and your auth token as the password for HTTP Basic authentication.


_10curl -XPOST https://verify.twilio.com/v2/Services \
_10    -d FriendlyName=MyServiceName \
_10    -u '[YOUR ACCOUNT SID]:[YOUR AUTH TOKEN]'

You can find your account SID and auth token in your console.

User Verification Workflow

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.

Step 1: Create a Verification Service

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_18// Download the helper library from https://www.twilio.com/docs/node/install
_18const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18// Find your Account SID and Auth Token at twilio.com/console
_18// and set the environment variables. See http://twil.io/secure
_18const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18const authToken = process.env.TWILIO_AUTH_TOKEN;
_18const client = twilio(accountSid, authToken);
_18
_18async function createService() {
_18  const service = await client.verify.v2.services.create({
_18    friendlyName: "My First Verify Service",
_18  });
_18
_18  console.log(service.sid);
_18}
_18
_18createService();

Output


_43{
_43  "sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_43  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_43  "friendly_name": "My First Verify Service",
_43  "code_length": 4,
_43  "lookup_enabled": false,
_43  "psd2_enabled": false,
_43  "skip_sms_to_landlines": false,
_43  "dtmf_input_required": false,
_43  "tts_name": "name",
_43  "mailer_sid": "MDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_43  "do_not_share_warning_enabled": false,
_43  "custom_code_enabled": true,
_43  "push": {
_43    "include_date": false,
_43    "apn_credential_sid": "CRaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_43    "fcm_credential_sid": null
_43  },
_43  "totp": {
_43    "issuer": "test-issuer",
_43    "time_step": 30,
_43    "code_length": 3,
_43    "skew": 2
_43  },
_43  "whatsapp": {
_43    "msg_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_43    "from": "whatsapp:+1234567890"
_43  },
_43  "default_template_sid": "HJaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_43  "verify_event_subscription_enabled": false,
_43  "date_created": "2015-07-30T20:00:00Z",
_43  "date_updated": "2015-07-30T20:00:00Z",
_43  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_43  "links": {
_43    "verification_checks": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/VerificationCheck",
_43    "verifications": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Verifications",
_43    "rate_limits": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/RateLimits",
_43    "messaging_configurations": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/MessagingConfigurations",
_43    "entities": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities",
_43    "webhooks": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Webhooks",
_43    "access_tokens": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AccessTokens"
_43  }
_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.

Step 2: Send a Verification Token

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_21// Download the helper library from https://www.twilio.com/docs/node/install
_21const 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
_21const accountSid = process.env.TWILIO_ACCOUNT_SID;
_21const authToken = process.env.TWILIO_AUTH_TOKEN;
_21const client = twilio(accountSid, authToken);
_21
_21async function createVerification() {
_21  const verification = await client.verify.v2
_21    .services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_21    .verifications.create({
_21      channel: "sms",
_21      to: "+15017122661",
_21    });
_21
_21  console.log(verification.status);
_21}
_21
_21createVerification();

Output


_23{
_23  "sid": "VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_23  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_23  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_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": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_23    }
_23  ],
_23  "sna": null,
_23  "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 Overview
call
email , checkout the guide Send Email Verifications with Verify and Twilio SendGrid
whatsapp , 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.

Verification documentation.

Step 3: Check the Verification Token

Node.js

Python

Java

PHP

Ruby

twilio-cli

curl


_21// Download the helper library from https://www.twilio.com/docs/node/install
_21const 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
_21const accountSid = process.env.TWILIO_ACCOUNT_SID;
_21const authToken = process.env.TWILIO_AUTH_TOKEN;
_21const client = twilio(accountSid, authToken);
_21
_21async function createVerificationCheck() {
_21  const verificationCheck = await client.verify.v2
_21    .services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_21    .verificationChecks.create({
_21      code: "123456",
_21      to: "+15017122661",
_21    });
_21
_21  console.log(verificationCheck.status);
_21}
_21
_21createVerificationCheck();

Output


_14{
_14  "sid": "VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_14  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_14  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_14  "to": "+15017122661",
_14  "channel": "sms",
_14  "status": "approved",
_14  "valid": true,
_14  "amount": null,
_14  "payee": null,
_14  "sna_attempts_error_codes": [],
_14  "date_created": "2015-07-30T20:00:00Z",
_14  "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.

(information)

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.