Menu

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?

REST API: Authorization Documents

Hosted Numbers API is currently in private Developer Preview

An Authorization Document is a resource representing a legally binding document between Twilio and a customer to Authorize Twilio to run SMS traffic on a given set of Phone Numbers. Hosted Number Orders can be assigned to an Authorization Document detailing which Address a Hosted Number Order is activated with. Once the Authorization Document has been signed, the Hosted Number Orders will then be registered to Twilio for routing capability.

Authorization Document Instance Resource

Resource URI

preview.twilio.com/HostedNumbers/AuthorizationDocuments/{SID}

The public URI above allows HTTP requests to perform actions if a valid account sid and authorization token are supplied. Web applications can hide their authorization token providing extra security to Twilio applications.

Resource Properties

An Authorization Document resource is represented by the following properties:

Names in PHP format
sid
sid<PX> Not PII

A 34 character string that uniquely identifies this AuthorizationDocument.

addressSid
sid<AD> Not PII

A 34 character string that uniquely identifies the Address resource that is associated with this AuthorizationDocument.

status
enum:status Not PII

Status of an instance resource. It can hold one of the values: 1. opened 2. signing, 3. signed LOA, 4. canceled, 5. failed. See the section entitled Status Values for more information on each of these statuses.

email

Email that this AuthorizationDocument will be sent to for signing.

ccEmails
string[] PII MTL: 30 DAYS

Email recipients who will be informed when an Authorization Document has been sent and signed.

dateCreated
date_time<iso8601> Not PII

The date this resource was created, given as GMT RFC 2822 format.

dateUpdated
date_time<iso8601> Not PII

The date that this resource was updated, given as GMT RFC 2822 format.

url
url Not PII

links
uri_map Not PII

AuthorizationDocuments Status Values

Status Description
opened Document is open and mutable.
signing Document has been sent out to the Email for signature and is immutable.
signed Document has been signed by the Email recipient and is immutable.
canceled Document has been canceled by the Email recipient and is immutable.
failed Document has failed with an error and is immutable.
        
        
        
        

        HTTP POST

        Requests to update a single, existing Authorization Documents instance resource’s properties and returns the updated resource representation if successful. The returned response is identical to that returned above when making a GET request.

        Optional Parameters

        HTTP POST actions can change the data of the Authorization Document instance resource with the following optional parameters.

        Note: Authorization Documents can only be updated when in opened status. To edit, POST Status to opened.

        Names in PHP format
        hostedNumberOrderSids
        Optional
        post string[] Not PII

        A list of HostedNumberOrder sids that this AuthorizationDocument will authorize for hosting phone number capabilities on Twilio's platform.

        addressSid
        Optional
        post sid<AD> Not PII

        A 34 character string that uniquely identifies the Address resource that is associated with this AuthorizationDocument.

        email
        Optional
        post string PII MTL: 30 DAYS

        Email that this AuthorizationDocument will be sent to for signing.

        ccEmails
        Optional
        post string[] PII MTL: 30 DAYS

        Email recipients who will be informed when an Authorization Document has been sent and signed

        status
        Optional
        post enum:status Not PII

        Status of an instance resource. It can hold one of the values: 1. opened 2. signing, 3. signed LOA, 4. canceled, 5. failed. See the section entitled Status Values for more information on each of these statuses.

        contactTitle
        Optional
        post string Not PII

        The title of the person authorized to sign the Authorization Document for this phone number.

        contactPhoneNumber
        Optional
        post string PII MTL: 30 DAYS

        The contact phone number of the person authorized to sign the Authorization Document.

              
              
              
              

              HTTP GET

              Returns a single, existing Authorization Document instance resource specified by the requested Hosted Number Orders instance resource SID.

              HTTP DELETE

              DELETE is not currently supported in Developer Preview.

                    
                    
                    
                    

                    AuthorizationDocuments List Resource

                    The Authorization Documents list resource represents the list of active and inactive Authorization Documents for the account.

                    Resource URI

                    preview.twilio.com/HostedNumbers/AuthorizationDocuments
                    

                    Resource Properties

                    An Authorization Document resource is represented by the following properties:

                    Names in PHP format
                    sid
                    sid<PX> Not PII

                    A 34 character string that uniquely identifies this AuthorizationDocument.

                    addressSid
                    sid<AD> Not PII

                    A 34 character string that uniquely identifies the Address resource that is associated with this AuthorizationDocument.

                    status
                    enum:status Not PII

                    Status of an instance resource. It can hold one of the values: 1. opened 2. signing, 3. signed LOA, 4. canceled, 5. failed. See the section entitled Status Values for more information on each of these statuses.

                    email

                    Email that this AuthorizationDocument will be sent to for signing.

                    ccEmails
                    string[] PII MTL: 30 DAYS

                    Email recipients who will be informed when an Authorization Document has been sent and signed.

                    dateCreated
                    date_time<iso8601> Not PII

                    The date this resource was created, given as GMT RFC 2822 format.

                    dateUpdated
                    date_time<iso8601> Not PII

                    The date that this resource was updated, given as GMT RFC 2822 format.

                    url
                    url Not PII

                    links
                    uri_map Not PII

                    List Filters

                    There are two list filters that can be used for the list resource.

                    Names in PHP format
                    email
                    Optional
                    get string PII MTL: 30 DAYS

                    Email that this AuthorizationDocument will be sent to for signing.

                    status
                    Optional
                    get enum:status Not PII

                    Status of an instance resource. It can hold one of the values: 1. opened 2. signing, 3. signed LOA, 4. canceled, 5. failed. See the section entitled Status Values for more information on each of these statuses.

                    HTTP GET

                    Retrieves a list of all HostedNumberOrders for an account and their properties.

                          
                          
                          
                          

                          HTTP POST

                          Create an Authorization Document for authorizing the hosting of phone number's capability on Twilio's platform. The resource is explicit and all Hosted Number Orders added upon creation are the entire list of numbers that are assigned to the Authorization Document. Once the POST to create a new Authorization Document has been created, the LOA will immediately be sent out for signature.

                          Note: To update the Authorization Document, update the Status to opened.

                          Required Parameters

                          Parameters Description
                          HostedNumberOrderSids A list of HostedNumberOrder sids that this AuthorizationDocument will authorize for hosting phone number capabilities on Twilio's platform.
                          AddressSid This is the reference to the Address resource whose address is associated with the phone number’s owner. This address will be referenced in the LOA.
                          Email The email of the owner of the phone number. Must be authorized to sign the LOA document.
                          ContactTitle +E.164 formatted phone number of the contact person that will be signing the Authorization Document on behalf of the phone numbers
                          ContactPhoneNumber Formal title of the contact person that will be signing the Authorization Document if a business, otherwise can be Mr, Mrs, or Ms.

                          Optional Parameters

                          Parameters Description
                          CCEmails List of emails that the LOA document will be carbon copied to.

                          HTTP DELETE

                          There is no DELETE functionality for Authorization Documents List Resource.

                                
                                
                                
                                

                                Note: Creating a new instance from the list resource is implicit. Any HostedNumberOrderSids passed will be the full list of HNOs. If a HostedNumberOrderSid is in pending-loa and assigned to a SigningDocumentSid, an error in the response will be received. To remove all HostedNumberOrderSids from the Authorization Document, you can POST with an empty parameter.

                                      
                                      
                                      
                                      

                                      Authorization Documents DependentOrders List Resource

                                      The list of dependent Hosted Number Orders mapped to the Authorization Document instance resource. The Hosted Number Orders will be moved to the registration phase once the Authorization Document has been signed and accepted.

                                      Resource URI

                                      preview.twilio.com/HostedNumbers/AuthorizationDocuments/{SID}/DependentOrders
                                      

                                      parameters

                                      The resource properties of Depdent Orders is the same as the Orders resource

                                      List Filters

                                      There are no list filters at this time.

                                      HTTP GET

                                      Retrieves a list of all HostedNumberOrders for an account.

                                      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.