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

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:

For more information on Verify, see our product page(link takes you to an external page).


Base URL

base-url page anchor

All URLs referenced in the documentation have the following base:


_10
https://verify.twilio.com/v2/

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


HTTP requests to the REST API are protected with HTTP Basic authentication(link takes you to an external page). 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.


_10
curl -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(link takes you to an external page).


User Verification Workflow

user-verification-workflow page anchor

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

step-1-create-a-verification-service page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

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

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:

  1. In the Twilio Verify Console(link takes you to an external page)
  2. 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:

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

step-2-send-a-verification-token page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

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

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:

Learn more about how to turn phone number input into E.164 format(link takes you to an external page) or how to customize the verification message.

Verification documentation.

Step 3: Check the Verification Token

step-3-check-the-verification-token page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_17
// Download the helper library from https://www.twilio.com/docs/node/install
_17
import twilio from "twilio";
_17
_17
// Find your Account SID and Auth Token at twilio.com/console
_17
// and set the environment variables. See http://twil.io/secure
_17
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_17
const authToken = process.env.TWILIO_AUTH_TOKEN;
_17
const client = twilio(accountSid, authToken);
_17
_17
const verificationCheck = await client.verify.v2
_17
.services("VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_17
.verificationChecks.create({
_17
code: "123456",
_17
to: "+15017122661",
_17
});
_17
_17
console.log(verificationCheck.status);

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.

TokenStatus in response
Correctapproved
Incorrectpending

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.


Rate this page: