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

Verification Attempts


(information)

Info

The Verification Attempts API is currently in the Public Beta release stage!

Please note that Verification Attempts API currently only supports SMS, WhatsApp, and Voice channels.

The Verification Attempts API allows you to list and filter verification attempts generated by your Verify V2 services in the last 30 days.

A verification attempt is a communication attempt with the end user that contains a verification code and uses one of the channels supported by Twilio Verify. A single verification may generate one or more verification attempts.

This API contains two endpoints:

  1. List Multiple Verification Attempts : Returns a list of verification attempts that match the selected query parameters. Each verification attempt includes information such as channel specific data, conversion status, and price.
  2. Fetch a Verification Attempt : Returns a specific verification attempt by SID.

You can get a summary of verification attempts including total conversions and conversion rate percentage using the Verification Attempts Summary API.

Verification Attempts API currently supports the SMS, Call and WhatsApp channel.


Rate limits

rate-limits page anchor

Verification Attempts API provides a built-in rate limit of 100 requests per minute. If you reach this limit, you will start receiving HTTP 429 "Too Many Requests" responses.


Verification Attempts API has a timeout value of 15 seconds. However, its 99th percentile is within 1 second.


Verification Attempts API has a default value of 50 items per page. The number of items per page can be controlled by the PageSize query string parameter. Valid values range from 1 to 1000 items per page.


Verification Attempt Response Properties

verification-attempt-response-properties page anchor

These properties are returned in the JSON response output. The values of some fields may change over time to reflect their current status, most notably message_status and price.

message_status

message_status page anchor

This field will reflect the message's outbound progression until it reaches a final delivery outcome. Learn more here about possible message statuses and their meanings(link takes you to an external page).

This field will reflect the current calculated price of the message. It may change depending on the message's outbound status and delivery outcome. Pricing is dependent on a number of factors including carriers used, verification delivery attempt count and number of message segments for each SMS. Final pricing data may not be available until 24 hours after message delivery.

Please note that for some countries (e.g. China) or carriers, we may not be able to fetch message_status and price info.

Resource properties
sidtype: SID<VL>Not PII

The SID that uniquely identifies the verification attempt resource.


account_sidtype: SID<AC>Not PII

The SID of the Account(link takes you to an external page) that created the Verification resource.


service_sidtype: SID<VA>Not PII

The SID of the Service(link takes you to an external page) used to generate the attempt.


verification_sidtype: SID<VE>Not PII

The SID of the Verification(link takes you to an external page) that generated the attempt.


date_createdtype: string<DATE TIME>Not PII

The date that this Attempt was created, given in ISO 8601(link takes you to an external page) format.


date_updatedtype: string<DATE TIME>Not PII

The date that this Attempt was updated, given in ISO 8601(link takes you to an external page) format.


conversion_statustype: enum<STRING>Not PII

A string specifying the conversion status of the verification. A conversion happens when the user is able to provide the correct code. Possible values are CONVERTED and UNCONVERTED.

Possible values:
convertedunconverted

channeltype: enum<STRING>Not PII

A string specifying the communication channel used for the verification attempt. i.e SMS, CALL, etc.

Possible values:
smscallemailwhatsapp

pricetype: objectNot PII

An object containing the charge for this verification attempt related to the channel costs and the currency used. The costs related to the succeeded verifications are not included. May not be immediately available. More information on pricing is available here(link takes you to an external page).


channel_datatype: objectNot PII

An object containing the channel specific information for an attempt.


urltype: string<URI>Not PII

Fetch a Verification Attempt

fetch-a-verification-attempt page anchor
GET https://verify.twilio.com/v2/Attempts/{Sid}

Returns a single verification attempt specified by the provided SID.

Parameters

fetch-parameters page anchor
URI parameters
Sidtype: SID<VL>Not PII
Path Parameter

The unique SID identifier of a Verification Attempt

Fetch a VerificationAttempt

fetch-a-verificationattempt page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.verify.v2.verificationAttempts('VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10
.fetch()
_10
.then(verification_attempt => console.log(verification_attempt.sid));

Output

_28
{
_28
"sid": "VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_28
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_28
"service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_28
"verification_sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_28
"date_created": "2020-08-11T18:36:59Z",
_28
"date_updated": "2020-08-11T18:37:00Z",
_28
"conversion_status": "unconverted",
_28
"channel": "sms",
_28
"price": {
_28
"value": "0.005",
_28
"currency": "usd"
_28
},
_28
"channel_data": {
_28
"verification_sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_28
"to": "+573003003030",
_28
"status": "unconfirmed",
_28
"message_status": "undelivered",
_28
"error_code": "30008",
_28
"country": "CO",
_28
"code_length": 6,
_28
"locale": "es",
_28
"mcc": "732",
_28
"mnc": "103",
_28
"carrier": "Colombia Movil (Tigo)"
_28
},
_28
"url": "https://verify.twilio.com/v2/Attempts/VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_28
}


List Multiple Verification Attempts

list-multiple-verification-attempts page anchor
GET https://verify.twilio.com/v2/Attempts

Returns a paginated list of verification attempts that match the selected query parameters.

Below are the available query parameters for selecting and filtering verification attempts. An empty array is returned if there are no matches.

URI parameters
DateCreatedAftertype: string<DATE TIME>Not PII
Query Parameter

Datetime filter used to consider only Verification Attempts created after this datetime on the summary aggregation. Given as GMT in ISO 8601 formatted datetime string: yyyy-MM-dd'T'HH:mm:ss'Z.


DateCreatedBeforetype: string<DATE TIME>Not PII
Query Parameter

Datetime filter used to consider only Verification Attempts created before this datetime on the summary aggregation. Given as GMT in ISO 8601 formatted datetime string: yyyy-MM-dd'T'HH:mm:ss'Z.


ChannelData.Totype: stringNot PII
Query Parameter

Destination of a verification. It is phone number in E.164 format.


Countrytype: string<ISO COUNTRY CODE>Not PII
Query Parameter

Filter used to query Verification Attempts sent to the specified destination country.


Channeltype: enum<STRING>Not PII
Query Parameter

Filter used to query Verification Attempts by communication channel. Valid values are SMS and CALL

Possible values:
smscallemailwhatsapp

VerifyServiceSidtype: SID<VA>Not PII
Query Parameter

Filter used to query Verification Attempts by verify service. Only attempts of the provided SID will be returned.


VerificationSidtype: SID<VE>Not PII
Query Parameter

Filter used to return all the Verification Attempts of a single verification. Only attempts of the provided verification SID will be returned.


Statustype: enum<STRING>Not PII
Query Parameter

Filter used to query Verification Attempts by conversion status. Valid values are UNCONVERTED, for attempts that were not converted, and CONVERTED, for attempts that were confirmed.

Possible values:
convertedunconverted

PageSizetype: integerNot PII
Query Parameter

How many resources to return in each list page. The default is 50, and the maximum is 1000.


Pagetype: integerNot PII
Query Parameter

The page index. This value is simply for client state.


PageTokentype: stringNot PII
Query Parameter

The page token. This is provided by the API.

List Verification Attempts

list-verification-attempts page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.verify.v2.verificationAttempts
_10
.list({limit: 20})
_10
.then(verificationAttempts => verificationAttempts.forEach(v => console.log(v.sid)));

Output

_12
{
_12
"attempts": [],
_12
"meta": {
_12
"key": "attempts",
_12
"page": 0,
_12
"page_size": 50,
_12
"first_page_url": "https://verify.twilio.com/v2/Attempts?PageSize=50&Page=0",
_12
"previous_page_url": "https://verify.twilio.com/v2/Attempts?PageSize=50&Page=0",
_12
"url": "https://verify.twilio.com/v2/Attempts?PageSize=50&Page=0",
_12
"next_page_url": "https://verify.twilio.com/v2/Attempts?PageSize=50&Page=1"
_12
}
_12
}

List Unconverted Verification Attempts Sent to Colombia

list-unconverted-verification-attempts-sent-to-colombia page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.verify.v2.verificationAttempts
_10
.list({country: 'CO', status: 'UNCONVERTED', limit: 20})
_10
.then(verificationAttempts => verificationAttempts.forEach(v => console.log(v.sid)));

Output

_41
{
_41
"attempts": [
_41
{
_41
"sid": "VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_41
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_41
"service_sid": "VAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_41
"verification_sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_41
"date_created": "2020-08-11T18:36:59Z",
_41
"date_updated": "2020-08-11T18:37:00Z",
_41
"conversion_status": "unconverted",
_41
"channel": "sms",
_41
"price": {
_41
"value": "0.005",
_41
"currency": "usd"
_41
},
_41
"channel_data": {
_41
"verification_sid": "VEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_41
"to": "+573003003030",
_41
"status": "unconfirmed",
_41
"message_status": "undelivered",
_41
"error_code": "30008",
_41
"country": "CO",
_41
"code_length": 6,
_41
"locale": "es",
_41
"mcc": "732",
_41
"mnc": "103",
_41
"carrier": "Colombia Movil (Tigo)"
_41
},
_41
"url": "https://verify.twilio.com/v2/Attempts/VLXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
_41
}
_41
],
_41
"meta": {
_41
"key": "attempts",
_41
"page": 0,
_41
"page_size": 50,
_41
"first_page_url": "https://verify.twilio.com/v2/Attempts?PageSize=50&Page=0",
_41
"previous_page_url": "https://verify.twilio.com/v2/Attempts?PageSize=50&Page=0",
_41
"url": "https://verify.twilio.com/v2/Attempts?PageSize=50&Page=0",
_41
"next_page_url": "https://verify.twilio.com/v2/Attempts?PageSize=50&Page=1"
_41
}
_41
}

List Verification Attempts With No Matches Returned

list-verification-attempts-with-no-matches-returned page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.verify.v2.verificationAttempts
_10
.list({verificationSid: 'VL_UNKNOWN_SID', limit: 20})
_10
.then(verificationAttempts => verificationAttempts.forEach(v => console.log(v.sid)));

Output

_12
{
_12
"attempts": [],
_12
"meta": {
_12
"key": "attempts",
_12
"page": 0,
_12
"page_size": 50,
_12
"first_page_url": "https://verify.twilio.com/v2/Attempts?PageSize=50&Page=0",
_12
"previous_page_url": "https://verify.twilio.com/v2/Attempts?PageSize=50&Page=0",
_12
"url": "https://verify.twilio.com/v2/Attempts?PageSize=50&Page=0",
_12
"next_page_url": "https://verify.twilio.com/v2/Attempts?PageSize=50&Page=1"
_12
}
_12
}


Rate this page: