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.
Please note that 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:
Verify Events is powered by Twilio's Event Streams API. You can also learn more about Event Streams API by reading its documentation or FAQ.
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.
There are currently six Verify Events that can be subscribed to via Event Streams, representing different states of a Verification.
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
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]
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": 043},44"expired_at": "2022-02-02T09:30:25.336676Z"45}46}47]
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]
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. |
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. |
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. |
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. |
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. |
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.
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.
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.
Verify Events are offered at no additional charge to Verify customers.