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

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

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

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.

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`.