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.comHostedNumbers/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:

address_sid
sid<AD> Not PII

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

cc_emails
string[] PII MTL: 30 DAYS

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

date_created
date_time<iso8601> Not PII

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

date_updated
date_time<iso8601> Not PII

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

email

Email that this AuthorizationDocument will be sent to for signing.

sid
sid<PX> Not PII

A 34 character string that uniquely identifies 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.

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.
Loading Code Sample...
      
      
      
      

      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.

      AddressSid
      Optional
      post sid<AD> Not PII

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

      CcEmails
      Optional
      post string[] Not PII

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

      ContactPhoneNumber
      Optional
      post string Not PII

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

      ContactTitle
      Optional
      post string Not PII

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

      Email
      Optional
      post string Not PII

      Email that this AuthorizationDocument will be sent to for signing.

      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.

      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.

      Loading Code Sample...
          
          
          
          

          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.

          Loading Code Sample...
              
              
              
              

              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:

              address_sid
              sid<AD> Not PII

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

              cc_emails
              string[] PII MTL: 30 DAYS

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

              date_created
              date_time<iso8601> Not PII

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

              date_updated
              date_time<iso8601> Not PII

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

              email

              Email that this AuthorizationDocument will be sent to for signing.

              sid
              sid<PX> Not PII

              A 34 character string that uniquely identifies 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.

              List Filters

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

              Email
              Optional
              get string Not PII

              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.

              Loading Code Sample...
                  
                  
                  
                  

                  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.

                  Loading Code Sample...
                      
                      
                      
                      

                      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.

                      Loading Code Sample...
                          
                          
                          
                          

                          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.

                          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.

                          Loading Code Sample...