Menu

Expand
Rate this page:

Verification Attempts

Verification Attempts API 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 the API.

Verification Attempts API now supports the SMS, WhatsApp and Voice channels.

The Verification Attempts API allows you to list and filter verification attempts generated by your Verify V2 services in the last 30 days.

A verification attempt is a communication attempt with the end user that contains a verification code and uses one of the channels supported by Twilio Verify. A single verification may generate one or more verification attempts.

This API contains two endpoints:

  1. List Multiple Verification Attempts: Returns a list of verification attempts that match the selected query parameters. Each verification attempt includes information such as channel specific data, conversion status, and price.
  2. Fetch a Verification Attempt: Returns a specific verification attempt by SID.

You can get a summary of verification attempts including total conversions and conversion rate percentage using the Verification Attempts Summary API.

Verification Attempts API currently supports only the SMS channel.

Rate limits

Verification Attempts API provides a built-in rate limit of 30 requests per minute. If you reach this limit, you will start receiving HTTP 429 "Too Many Requests" responses.

Timeouts

Verification Attempts API has a timeout value of 15 seconds. However, its 99th percentile is within 1 second.

Pagination

Verification Attempts API has a default value of 50 items per page. The number of items per page can be controlled by the PageSize query string parameter. Valid values range from 1 to 1000 items per page.

Verification Attempt Response Properties

These properties are returned in the JSON response output. The values of some fields may change over time to reflect their current status, most notably message_status and price.

message_status

This field will reflect the message's outbound progression until it reaches a final delivery outcome. Learn more here about possible message statuses and their meanings.

price

This field will reflect the current calculated price of the message. It may change depending on the message’s outbound status and delivery outcome. Pricing is dependent on a number of factors including carriers used, verification delivery attempt count and number of message segments for each SMS. Final pricing data may not be available until 24 hours after message delivery.

Resource Properties in REST API format
sid
sid<VL> Not PII

The SID that uniquely identifies the verification attempt resource.

account_sid
sid<AC> Not PII

The SID of the Account that created the Verification resource.

service_sid
sid<VA> Not PII

The SID of the Service used to generate the attempt.

verification_sid
sid<VE> Not PII

The SID of the Verification that generated the attempt.

date_created
date_time<iso8601> Not PII

The date that this Attempt was created, given in ISO 8601 format.

date_updated
date_time<iso8601> Not PII

The date that this Attempt was updated, given in ISO 8601 format.

conversion_status
enum:conversion_status Not PII

A string specifying the conversion status of the verification. A conversion happens when the user is able to provide the correct code. Possible values are CONVERTED and UNCONVERTED.

channel
enum:channels Not PII

A string specifying the communication channel used for the verification attempt. i.e SMS, CALL, etc.

price
object Not PII

An object containing the charge for this verification attempt related to the channel costs and the currency used. The costs related to the succeeded verifications are not included. May not be immediately available. More information on pricing is available here.

channel_data
object Not PII

An object containing the channel specific information for an attempt.

url
url Not PII

Fetch a Verification Attempt

get
https://verify.twilio.com/v2/Attempts/{Sid}

Returns a single verification attempt specified by the provided SID.

Parameters
Parameters in REST API format
sid
Path
get sid<VL> Not PII

The unique SID identifier of a Verification Attempt

Example 1
Loading Code Sample...
        
        

        Fetch Verification Attempt

        List Multiple Verification Attempts

        get
        https://verify.twilio.com/v2/Attempts

        Returns a paginated list of verification attempts that match the selected query parameters.

        Below are the available query parameters for selecting and filtering verification attempts. An empty array is returned if there are no matches.

        Parameters
        Parameters in REST API format
        date_created_after
        Optional
        get date_time<iso8601> Not PII

        Datetime filter used to query Verification Attempts created after this datetime. Given as GMT in RFC 2822 format.

        date_created_before
        Optional
        get date_time<iso8601> Not PII

        Datetime filter used to query Verification Attempts created before this datetime. Given as GMT in RFC 2822 format.

        channel_data.to
        Optional
        get string PII MTL: 30 DAYS

        Destination of a verification. It is phone number in E.164 format.

        country
        Optional
        get iso_country_code Not PII

        Filter used to query Verification Attempts sent to the specified destination country.

        channel
        Optional
        get ienum:channels Not PII

        Filter used to query Verification Attempts by communication channel. Valid values are SMS and CALL

        verify_service_sid
        Optional
        get sid<VA> Not PII

        Filter used to query Verification Attempts by verify service. Only attempts of the provided SID will be returned.

        verification_sid
        Optional
        get sid<VE> Not PII

        Filter used to return all the Verification Attempts of a single verification. Only attempts of the provided verification SID will be returned.

        status
        Optional
        get ienum:conversion_status Not PII

        Filter used to query Verification Attempts by conversion status. Valid values are UNCONVERTED, for attempts that were not converted, and CONVERTED, for attempts that were confirmed.

        Example 1
        Loading Code Sample...
              
              

              List Verification Attempts

              Example 2
              Loading Code Sample...
                    
                    

                    List Unconverted Verification Attempts Sent to Colombia

                    Example 3
                    Loading Code Sample...
                          
                          

                          List Verification Attempts With No Matches Returned

                          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.

                          Loading Code Sample...
                                
                                
                                

                                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