Verification Stream

Verification status events

Verification Status tracks the overall lifecycle of a verification — from creation to resolution. It fires events when a verification transitions between states: PENDING, APPROVED, CANCELED, EXPIRED, or MAX_ATTEMPTS_REACHED. Each event includes the full context of the verification: all send code attempts, all check attempts, and timestamps for each state change.

Event types

You can subscribe to five verification status events through Event Streams, representing different states of a verification.

Event type	Event type string	Description and timing
Verification pending	`com.twilio.accountsecurity.verify.verification.pending`	This event fires after a successful Start New Verification API call, when the verification is pending further action from the end user or client.
Verification approved	`com.twilio.accountsecurity.verify.verification.approved`	This event fires after a Check Verification API call returns an `approved` status, or after an Update a Verification Status API call sets the status to `approved`.
Verification canceled	`com.twilio.accountsecurity.verify.verification.canceled`	This event fires after an Update a Verification Status API call sets the verification status to `canceled`.
Verification expired	`com.twilio.accountsecurity.verify.verification.expired`	This event fires after a verification expires. The default expiration time is 10 minutes after creation.
Verification max attempts reached	`com.twilio.accountsecurity.verify.verification.max-attempts-reached`	This event fires after a verification fails from 5 or more send or check attempts.

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            "locale": "en",
31            "tags": {
32              "custom_tag": "test tag 1",
33              "custom_tag_2": "test tag 1_2"
34            }
35          },
36          {
37            "time": "2022-08-24T12:49:44.356564Z",
38            "channel": "SMS",
39            "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa2",
40            "locale": "en",
41            "tags": {
42              "custom_tag": "test tag 2",
43              "custom_tag_2": "test tag 2_2"
44            }
45          }
46        ]
47      },
48      "check_attempts": {
49        "count": 1,
50        "attempts": [
51          {
52            "time": "2022-02-02T09:20:25.336676Z",
53            "status": "SUCCESS"
54          }
55        ]
56      },
57      "expired_at": "2022-02-02T09:30:25.336676Z"
58    }
59  }
60]

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            "locale": "en",
29            "tags": {
30              "custom_tag": "test tag 1"
31            }
32          },
33          {
34            "time": "2022-08-24T12:49:44.356564Z",
35            "channel": "SMS",
36            "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa2",
37            "locale": "en",
38            "tags": {
39              "custom_tag": "test tag 2"
40            }
41          }
42        ]
43      },
44      "check_attempts": {
45        "count": 0
46      },
47      "expired_at": "2022-02-02T09:30:25.336676Z"
48    }
49  }
50]

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            "locale": "en",
30            "tags": {
31              "custom_tag": "test tag 1",
32              "custom_tag_2": "test tag 1_2"
33            }
34          },
35          {
36            "time": "2022-08-24T12:49:44.356564Z",
37            "channel": "SMS",
38            "attempt_sid": "VLaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa2",
39            "locale": "en",
40            "tags": {
41              "custom_tag": "test tag 2",
42              "custom_tag_2": "test tag 2_2"
43            }
44          }
45        ]
46      },
47      "check_attempts": {
48        "count": 1,
49        "attempts": [
50          {
51            "time": "2022-02-02T09:20:25.336676Z",
52            "status": "SUCCESS"
53          }
54        ]
55      },
56      "expired_at": "2022-02-02T09:30:25.336676Z"
57    }
58  }
59]

Event resource properties

The verification status events you receive are based on a common schema of the following properties. Some properties are only present if they apply to that specific verification event; otherwise, they are null.

Property	Type	Description
`account_sid`	`string`	The SID 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`	Returns `true` if you sent the verification with a custom code, `false` otherwise.
`code_length`	`integer`	The verification code length. Returns `null` if a custom code is used.
`send_code_attempts`	`object`	An object containing information about sent Verification Attempts. See SendCodeAttempts property definitions.
`check_attempts`	`object`	An object containing information about Verification Check attempts. See CheckAttempts property definitions.

SendCodeAttempts properties

The Verification Status 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 of `SendCodeAttemptsList` objects with information on each Verification Attempt. See `SendCodeAttemptsList` property definitions here.

SendCodeAttemptsList properties

The Verification Status 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.
`locale`	`string`	The language used for the Verification Attempt.
`tags`	`object`	The set of custom tags added to an attempt when including the tags parameter in the Start New Verification endpoint

CheckAttempts properties

The Verification Status 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 Verification Status 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`.