Verify Events

(information)

Verify Events is in Pilot

This Verify feature is currently in the Pilot maturity stage, which means that we're actively looking for early-adopter customers to try it out and give feedback. That could be you.

Onboarding is now a self-serve process, follow our Verify Events Onboarding Guide for a step-by-step walkthrough.

Verify Events currently only supports SMS, WhatsApp, and Voice channels.

Verify Events helps your business by providing instantaneous, real-time information on the activity of your Verify Service. It is supported by Twilio Event Streams API, an API that allows you to tap into a unified stream of interactions across different Twilio products. Use Verify Events for granular visibility to track:

Verification delivery statuses
Verification success rates
Latency
Overall performance

Getting started with Event Streams API

Verify Events is powered by Twilio's Event Streams API. Learn more about Event Streams.

You can stream Verify Events data to your existing systems by configuring a modern, persistent streaming technology like Amazon Kinesis or to a webhook.

Amazon Kinesis is a data streaming platform where you can collect and process large streams of data in real time. Amazon Kinesis is within the AWS ecosystem, so its infrastructure is fully managed for you and it is easily scalable with low latency.

Webhooks, or status callbacks, are HTTP requests that are triggered to send to a user-defined URL when events happen. With this option, Event Streams API will send either an HTTP POST or an HTTP GET request to the URL you specify. The request body will contain all of the information about that incoming Verify Event.

Onboarding onto Verify Events on Event Streams is now a self-serve process, follow our Verify Events Onboarding Guide for a step-by-step walkthrough.

Event types

There are currently six Verify Events that can be subscribed to via Event Streams, representing different states of a Verification.

Verification Pending

Event Type String	`com.twilio.accountsecurity.verify.verification.pending`
Description and Timing	Event is emitted after a Start New Verification API call is successfully made, and a Verification is pending further action from the end user or client.

Verification Approved

Event Type String	`com.twilio.accountsecurity.verify.verification.approved`
Description and Timing	Event is emitted after a Check Verification API call is made and it returns that a Verification's status is `approved`, or a Update a Verification Status API call is made with the status `approved`.

Verification Canceled

Event Type String	`com.twilio.accountsecurity.verify.verification.canceled`
Description and Timing	Event is emitted after an Update a Verification Status API call is made for a Verification with the status `canceled`.

Verification Expired

Event Type String	`com.twilio.accountsecurity.verify.verification.expired`
Description and Timing	Event is emitted after a Verification expires. The default expiration time is 10 minutes after Verification creation.

Verification Max Attempts Reached

Event Type String	`com.twilio.accountsecurity.verify.verification.max-attempts-reached`
Description and Timing	Event is emitted after a Verification fails from either attempting to send or check the Verification 5 or more times.

Sample event payloads

Sample event payload with custom code disabled

1[
2  {
3    "specversion": "1.0",
4    "type": "com.twilio.accountsecurity.verify.verification.approved",
5    "source": "/v1/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Verifications/VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6    "id": "50ae352aa7c98cbae53b8d0e6c0767b9a445b74e029bfb4f8c7d6efba8ca260b",
7    "dataschema": "https://events-schemas.twilio.com/AccountSecurity.VerifyEventStreamEvent/1",
8    "datacontenttype": "application/json",
9    "time": "2022-02-02T09:20:25.336Z",
10    "data": {
11      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
12      "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13      "verification_sid": "VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14      "friendly_name": "my service",
15      "custom_code_enabled": false,
16      "custom_friendly_name": "custom friendly name",
17      "created_at": "2022-02-02T09:20:25.336676Z",
18      "verified_at": "2022-02-02T09:20:25.336676Z",
19      "to": "+919999999999",
20      "verification_status": "APPROVED",
21      "country": "IN",
22      "code_length": 4,
23      "send_code_attempts": {
24        "count": 2,
25        "attempts": [
26          {
27            "time": "2022-08-24T12:49:09.598837Z",
28            "channel": "SMS",
29            "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1",
30            "delivery_status": "DELIVERY_UNKNOWN",
31            "error_code": "30008",
32            "locale": "en"
33          },
34          {
35            "time": "2022-08-24T12:49:44.356564Z",
36            "channel": "SMS",
37            "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa2",
38            "delivery_status": "DELIVERED",
39            "locale": "en"
40          }
41        ]
42      },
43      "check_attempts": {
44        "count": 1,
45        "attempts": [
46          {
47            "time": "2022-02-02T09:20:25.336676Z",
48            "status": "SUCCESS"
49          }
50        ]
51      },
52      "expired_at": "2022-02-02T09:30:25.336676Z"
53    }
54  }
55]

Sample event payload with custom code enabled and feedback disabled

1[
2  {
3    "specversion": "1.0",
4    "type": "com.twilio.accountsecurity.verify.verification.pending",
5    "source": "/v1/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Verifications/VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6    "id": "50ae352aa7c98cbae53b8d0e6c0767b9a445b74e029bfb4f8c7d6efba8ca260b",
7    "dataschema": "https://events-schemas.twilio.com/AccountSecurity.VerifyEventStreamEvent/1",
8    "datacontenttype": "application/json",
9    "time": "2022-02-02T09:20:25.336Z",
10    "data": {
11      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
12      "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13      "verification_sid": "VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14      "friendly_name": "my service",
15      "custom_code_enabled": true,
16      "custom_friendly_name": "custom friendly name",
17      "created_at": "2022-02-02T09:20:25.336676Z",
18      "to": "+919999999999",
19      "verification_status": "PENDING",
20      "country": "IN",
21      "send_code_attempts": {
22        "count": 2,
23        "attempts": [
24          {
25            "time": "2022-08-24T12:49:09.598837Z",
26            "channel": "SMS",
27            "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1",
28            "delivery_status": "DELIVERY_UNKNOWN",
29            "error_code": "30008",
30            "locale": "en"
31          },
32          {
33            "time": "2022-08-24T12:49:44.356564Z",
34            "channel": "SMS",
35            "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa2",
36            "delivery_status": "DELIVERED",
37            "locale": "en"
38          }
39        ]
40      },
41      "check_attempts": {
42        "count": 0
43      },
44      "expired_at": "2022-02-02T09:30:25.336676Z"
45    }
46  }
47]

Sample event payload with custom code enabled and feedback enabled

1[
2  {
3    "specversion": "1.0",
4    "type": "com.twilio.accountsecurity.verify.verification.approved",
5    "source": "/v1/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Verifications/VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
6    "id": "50ae352aa7c98cbae53b8d0e6c0767b9a445b74e029bfb4f8c7d6efba8ca260b",
7    "dataschema": "https://events-schemas.twilio.com/AccountSecurity.VerifyEventStreamEvent/1",
8    "datacontenttype": "application/json",
9    "time": "2022-02-02T09:20:25.336Z",
10    "data": {
11      "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
12      "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
13      "verification_sid": "VEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
14      "friendly_name": "my service",
15      "custom_code_enabled": true,
16      "custom_friendly_name": "custom friendly name",
17      "created_at": "2022-02-02T09:20:25.336676Z",
18      "verified_at": "2022-02-02T09:20:25.336676Z",
19      "to": "+919999999999",
20      "verification_status": "APPROVED",
21      "country": "IN",
22      "send_code_attempts": {
23        "count": 2,
24        "attempts": [
25          {
26            "time": "2022-08-24T12:49:09.598837Z",
27            "channel": "SMS",
28            "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa1",
29            "delivery_status": "DELIVERY_UNKNOWN",
30            "error_code": "30008",
31            "locale": "en"
32          },
33          {
34            "time": "2022-08-24T12:49:44.356564Z",
35            "channel": "SMS",
36            "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa2",
37            "delivery_status": "DELIVERED",
38            "locale": "en"
39          }
40        ]
41      },
42      "check_attempts": {
43        "count": 1,
44        "attempts": [
45          {
46            "time": "2022-02-02T09:20:25.336676Z",
47            "status": "SUCCESS"
48          }
49        ]
50      },
51      "expired_at": "2022-02-02T09:30:25.336676Z"
52    }
53  }
54]

Event resource properties

The Verify Events you receive are based on a common schema of the following properties. Note that some properties will only be present if they are applicable to that specific Verify event, otherwise they will be null.

Property	Type	Description
`account_sid`	`string`	The unique SID identifier of the Account that created the Verification.
`service_sid`	`string`	The unique SID identifier of the Verify Service that generated the Verification.
`verification_sid`	`string`	The unique SID identifier of the Verification.
`friendly_name`	`string`	The chosen friendly name of the Verify Service.
`custom_friendly_name`	`string`	If applicable, the custom friendly name of the Verify Service.
`created_at`	`string`	The date and time that the Verification was created in ISO 8601 format.
`verified_at`	`string`	If applicable, the date and time that the Verification was approved in ISO 8601 format.
`expired_at`	`string`	If applicable, the date and time that the Verification expired in ISO 8601 format.
`verification_status`	`string`	The status of the Verification, can be one of: `PENDING`, `APPROVED`, `CANCELED`, `EXPIRED`, `MAX_ATTEMPTS_REACHED`.
`to`	`string`	The Verification's destination phone number in E.164 format.
`country`	`string`	The country code that the Verification was delivered to.
`custom_code_enabled`	`boolean`	This will be `true` if the Verification was sent using a custom code and `false` if not.
`code_length`	`integer`	If applicable, the Verification code length. This will be `null` if a custom code is enabled.
`send_code_attempts`	`object`	An object containing information about sent Verification Attempts. See SendCodeAttempts property definitions here.
`check_attempts`	`object`	An object containing information about Verification Check attempts. See CheckAttempts property definitions here.

SendCodeAttempts properties

The Verify Event's send_code_attempts property provides information about all Verification Attempts sent to the end user for a Verification.

Property	Type	Description
`count`	`integer`	The total number of Verification Attempts sent.
`attempts`	`array`	If applicable, an array containing SendCodeAttemptsList objects contain information on each Verification Attempt. See SendCodeAttemptsList property definitions here.

SendCodeAttemptsList properties

The Verify Event's send_code_attempts property may contain an attempts array that holds SendCodeAttemptsList objects. The SendCodeAttemptsList object provides information about each Verification Attempt that was made.

Property	Type	Description
`time`	`string`	The date and time that the Verification Attempt was created in ISO 8601 format.
`channel`	`string`	The communication channel that was used, such as `SMS`.
`attempt_sid`	`string`	The unique SID identifier of the Verification Attempt.
`delivery_status`	`string`	If applicable, the message delivery status. Can be one of: `DELIVERED`, `UNDELIVERED`, `DELIVERY_UNKNOWN`, `SENT`, `FAILED`, `ACCEPTED`, `QUEUED`, `SENDING`. See this support article for more details on these statuses.
`error_code`	`string`	If applicable, the message delivery error code. See Twilio Error and Warning Dictionary for more details.
`locale`	`string`	The language used for the Verification Attempt.

CheckAttempts properties

The Verify Event's check_attempts property provides information about all Verification Checks that were made for a Verification.

Property	Type	Description
`count`	`integer`	The total number of Verification Checks made.
`attempts`	`array`	If applicable, an array containing CheckAttemptsList objects that contain information on each Verification Check. See CheckAttemptsList property definitions here.

CheckAttemptsList properties

The Verify Event's check_attempts property may contain an attempts array that holds CheckAttemptsList objects. The CheckAttemptsList object provides information about each Verification Check that was made.

Property	Type	Description
`time`	`string`	The date and time that the Verification Check was performed in ISO 8601 format.
`status`	`string`	The status of the Verification Check, can be one of: `SUCCESS`, `FAILURE`.

FAQ

What should I consider when choosing between using Verification Attempts API and Verify Events?

Verification Attempts API is a REST API that allows you to list and filter Verification Attempts generated by your Verify Service in the last 30 days. It is not real-time, but it can be used for reporting and troubleshooting.

Verify Events API is a real-time data stream that allows you to consume data about your Verifications using a streaming platform like Amazon Kinesis or with webhooks. It helps you to analyze granular data and build your own performance dashboards.

Are there any cases where Verification status cannot be determined?

If you have custom codes enabled and are not using the Update a Verification Status endpoint to report Verification status updates, Verify Events will not have verification status available.

How is Verification Attempt delivery status determined?

Delivery reporting status (DLR) is relayed to Twilio from each carrier. A message's delivery reporting is not always available right away if it is delayed from carriers. If delivery status is not available at the time a Verify Event is published, it will be listed as null. In that case, the Verify Events system will attempt to retrieve delivery status several times for up to 24 hours and will publish a second Event with the updated delivery status if found.

How much does using Verify Events cost?

Verify Events are offered at no additional charge to Verify customers.