Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Identities Pilot REST API

The Number Regulatory Compliance REST APIs are currently in a Public Pilot state. The new Regulatory Compliance APIs are under active development and will be debuted in Public Beta in September.

The Pilot Regulatory Compliance APIs will be deprecated when the new Regulatory Compliance APIs move to Public Beta. Please be mindful when building your application.

For access, please fill out the RC pilot request form.

Phone Numbers are a country's natural resource and may have regulations imposed by a given country's telephony regulatory body. To ensure the phone numbers provisioned to a customer's account or an account's end-users remain active, customers will need to comply with the varying levels of regulations. These regulations may require Proof of Identity and/or Address.

The Identities Public API resource allows management of end-user Identities that apply for provisioning access to a group of phone numbers with Identity and/or Address regulations.

Identities List Resource

The Identity list resource represents a list of Identities that are active, passed, or failed, with the instance metadata. Note: A more comprehensive lifecycle is under development.

Resource URI

numbers.twilio.com/v1/RegulatoryCompliance/Identities

Resource Properties

Resource Property Description
sid A 34 character string that uniquely identifies the Identity.
account_sid A 34 character string that uniquely identifies the account.
type An Identity type classifier; can be User or Company.
friendly_name A string that that can be configured to describe the resource for Identity management. pii mtl-30
email The email that will be receiving status updates on the lifecycle changes of the document(s). pii mtl-30
purchase_intent_iso_country The iso country of the intended purchase intent of the Identity.
purchase_intent_number_type The number type of the intended purchase intent of the Identity.
status The current status of the resource: Review, Passed, Failed.
status_callback_url The URL we call using the status_callback_method to send status information to your application.
status_callback_method The HTTP method we use to call status_callback. Can be: GET or POST.
date_created The date created of the Identity
date_updated The date updated of the Identity
url The URL to the Identities resource.

HTTP GET

Retrieves a list of all Identities for an account.

        
        
        
        
        Response

        List of the instance responses above.

        Identities Instance Resource

        The Identity instance resource represents a request to create an end-user Identity to comply with a country's number regulations for phone number provisioning on Twilio's platform. When the Identity for provisioning a group of phone numbers has been created and passed by Twilio, you can begin to provision phone numbers.

        Resource URI

        numbers.twilio.com/v1/RegulatoryCompliance/Identities/{IdentitySid}
        

        Resource Properties

        Resource Property Description
        sid A 34 character string that uniquely identifies the Identity.
        account_sid A 34 character string that uniquely identifies the account.
        type Identity type classifier; can be User or Company.
        friendly_name A user-defined friendly name for Identity management. pii mtl-30
        email The email that will be receiving status updates on the lifecycle changes of the document(s). pii mtl-30
        purchase_intent_iso_country The iso country of the intended purchase intent of the Identity.
        purchase_intent_number_type The number type of the intended purchase intent of the Identity.
        status The current status of the resource: Review, Passed, Failed.
        status_callback_url The URL we call using the status_callback_method to send status information to your application.
        status_callback_method The HTTP method we use to call status_callback. Can be: GET or POST.
        date_created The date created of the Identity
        date_updated The date updated of the Identity
        url The URL to the Identities resource.
        Response

        The returned response is identical to that returned when making a GET to a Identities instance response.

        Identities Status Values

        Note: A more comprehensive lifecycle is under development.

        Status Description
        Review The Identity is currently in review by Twilio and is no longer mutable.
        Passed The Identity has passed and can be used to complete the user's purchase intent.
        Failed The Identity has failed and can be mutated with more documents added to be submitted again for review.

        Identities Status Callback

        When an Identity changes status, Twilio will make an asynchronous HTTP request to the Status Callback Webhook, if configured on the Identity instance. By capturing this request, you can determine when the Identity changes status and if Failed, what the FailureReason is.

        The Identity status callback request passes the following parameters listed in the table below:

        Parameter Description
        AccountSid A 34 character string that uniquely identifies the account.
        IdentitySid A 34 character string that uniquely identifies the Identity.
        Status The new status of the Identity instance.
        FailureReason Details the reason as to why an Identity has failed.

        HTTP POST

        Creates a new Identity with associated metadata. The identity will move to the review status, prompting Twilio to review the Identity and the supporting Documents.

        Required Parameters

        Resource Parameter Description
        type Identity type classifier; can be User or Company.
        friendly_name A custom friendly name for Identity management. pii mtl-30
        email The email that will be receiving status updates on the lifecycle changes of the document(s). pii mtl-30
        purchase_intent_iso_country The iso country of the intended purchase intent of the Identity.
        purchase_intent_number_type The number type of the intended purchase intent of the Identity.
              
              
              
              

              HTTP GET

              Returns a single, existing end-user Identity instance resource specified by the requested Identity instance resource SID.

                    
                    
                    
                    

                    HTTP DELETE

                    Cancels the Identity, and consequently, deletes the corresponding Documents. Note that you can only issue the DELETE request when the Identity status is in review or failed. Any other active status will be prohibited from deletion.

                    Response

                    A successful request will result in an HTTP 204 with no response body.

                    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 browsing the Twilio tag on Stack Overflow.