Menu

Expand
Rate this page:

Verify Events

Verify Events is in Pilot!

This Verify feature is currently in the Pilot maturity stage, which means that:

1. We're actively looking for early-adopter customers to try it out and give feedback. That could be you!

2. You'll need to contact sales to request access to this feature.

Lastly, please note that Verify Events currently only supports the SMS channel.

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

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.

Your sales specialist will help you onboard onto Verify Events on Event Streams no matter which streaming technology you choose. You can learn more about Event Streams API by reading its documentation or FAQ.

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

        
        
        
              
              
              
                    
                    
                    

                    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.

                    Rate this page:

                    Need some help?

                    We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                          
                          
                          

                          Thank you for your feedback!

                          Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                          Sending your feedback...
                          🎉 Thank you for your feedback!
                          Something went wrong. Please try again.

                          Thanks for your feedback!

                          thanks-feedback-gif