Skip to contentSkip to navigationSkip to topbar
Twilio Docs
On this page

Authorization Document Resource

(error)

Danger

The Hosted Phone Numbers API is currently under development, and this documentation is for existing users. A new version will soon be released as a generally available (GA) product. Please be aware that the API path https://preview.twilio.com/HostedNumbers/AuthorizationDocuments will change with the GA release. You will be informed about the timeline and given time to update accordingly.

An Authorization Document is a resource representing a legally binding document between Twilio and a customer to Authorize Twilio to run messaging 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.

AuthorizationDocument Properties

authorizationdocument-properties page anchor
Property nameTypeRequiredDescriptionChild properties
sidSID<PX>

Optional

Not PII

A 34 character string that uniquely identifies this AuthorizationDocument.

Pattern: ^PX[0-9a-fA-F]{32}$Min length: 34Max length: 34
addressSidSID<AD>

Optional

Not PII

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

Pattern: ^AD[0-9a-fA-F]{32}$Min length: 34Max length: 34
statusenum<string>

Optional

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.

Possible values:
openedsigningsignedcanceledfailed
emailstring

Optional

PII MTL: 30 days

Email that this AuthorizationDocument will be sent to for signing.

ccEmailsarray[string]

Optional

PII MTL: 30 days

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

dateCreatedstring<date-time>

Optional

Not PII

The date this resource was created, given as GMT RFC 2822(link takes you to an external page) format.

dateUpdatedstring<date-time>

Optional

Not PII

The date that this resource was updated, given as GMT RFC 2822(link takes you to an external page) format.

urlstring<uri>

Optional

Not PII
linksobject<uri-map>

Optional

Not PII

Status Values

status-values page anchor
StatusDescription
openedDocument is open and mutable.
signingDocument has been sent out to the Email for signature and is immutable.
signedDocument has been signed by the Email recipient and is immutable.
canceledDocument has been canceled by the Email recipient and is immutable.
failedDocument has failed with an error and is immutable.

Create an AuthorizationDocument resource

create-an-authorizationdocument-resource page anchor

POST https://preview.twilio.com/HostedNumbers/AuthorizationDocuments

Create an Authorization Document for authorizing the hosting of phone numbers' 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.

Request body parameters

request-body-parameters page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
hostedNumberOrderSidsarray[string]
required
Not PII

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

addressSidSID<AD>
required
Not PII

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

Pattern: ^AD[0-9a-fA-F]{32}$Min length: 34Max length: 34
emailstring
required
PII MTL: 30 days

Email that this AuthorizationDocument will be sent to for signing.

contactTitlestring
required
Not PII

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

contactPhoneNumberstring
required
Not PII

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

ccEmailsarray[string]

Optional

PII MTL: 30 days

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

Create an AuthorizationDocumentLink to code sample: Create an AuthorizationDocument
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function createHostedNumbersAuthorizationDocument() {

11
  const authorizationDocument =

12
    await client.preview.hosted_numbers.authorizationDocuments.create({

13
      addressSid: "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

14
      contactPhoneNumber: "ContactPhoneNumber",

15
      contactTitle: "ContactTitle",

16
      email: "Email",

17
      hostedNumberOrderSids: ["HostedNumberOrderSids"],

18
    });

19


20
  console.log(authorizationDocument.sid);

21
}

22


23
createHostedNumbersAuthorizationDocument();

Response

1
{

2
  "address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "cc_emails": [

4
    "test1@twilio.com",

5
    "test2@twilio.com"

6
  ],

7
  "date_created": "2017-03-28T20:06:39Z",

8
  "date_updated": "2017-03-28T20:06:39Z",

9
  "email": "Email",

10
  "links": {

11
    "dependent_hosted_number_orders": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments/PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/DependentHostedNumberOrders"

12
  },

13
  "sid": "PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

14
  "status": "signing",

15
  "url": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments/PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

16
}

Fetch an AuthorizationDocument resource

fetch-an-authorizationdocument-resource page anchor

GET https://preview.twilio.com/HostedNumbers/AuthorizationDocuments/{Sid}

Path parameters

path-parameters page anchor
Property nameTypeRequiredPIIDescription
sidSID<PX>
required
Not PII

A 34 character string that uniquely identifies this AuthorizationDocument.

Pattern: ^PX[0-9a-fA-F]{32}$Min length: 34Max length: 34
Fetch an AuthorizationDocumentLink to code sample: Fetch an AuthorizationDocument
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function fetchHostedNumbersAuthorizationDocument() {

11
  const authorizationDocument = await client.preview.hosted_numbers

12
    .authorizationDocuments("PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .fetch();

14


15
  console.log(authorizationDocument.sid);

16
}

17


18
fetchHostedNumbersAuthorizationDocument();

Response

1
{

2
  "address_sid": "AD11111111111111111111111111111111",

3
  "cc_emails": [

4
    "aaa@twilio.com",

5
    "bbb@twilio.com"

6
  ],

7
  "date_created": "2017-03-28T20:06:39Z",

8
  "date_updated": "2017-03-28T20:06:39Z",

9
  "email": "test@twilio.com",

10
  "links": {

11
    "dependent_hosted_number_orders": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments/PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/DependentHostedNumberOrders"

12
  },

13
  "sid": "PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

14
  "status": "signing",

15
  "url": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments/PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

16
}

Read multiple AuthorizationDocument resources

read-multiple-authorizationdocument-resources page anchor

GET https://preview.twilio.com/HostedNumbers/AuthorizationDocuments

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
emailstring

Optional

PII MTL: 30 days

Email that this AuthorizationDocument will be sent to for signing.

statusenum<string>

Optional

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.

Possible values:
openedsigningsignedcanceledfailed
pageSizeinteger<int64>

Optional

Not PII

How many resources to return in each list page. The default is 50, and the maximum is 1000.

Minimum: 1Maximum: 1000
pageinteger

Optional

Not PII

The page index. This value is simply for client state.

Minimum: 0
pageTokenstring

Optional

Not PII

The page token. This is provided by the API.

List multiple AuthorizationDocumentsLink to code sample: List multiple AuthorizationDocuments
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listHostedNumbersAuthorizationDocument() {

11
  const authorizationDocuments =

12
    await client.preview.hosted_numbers.authorizationDocuments.list({

13
      limit: 20,

14
    });

15


16
  authorizationDocuments.forEach((a) => console.log(a.sid));

17
}

18


19
listHostedNumbersAuthorizationDocument();

Response

1
{

2
  "meta": {

3
    "first_page_url": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments?Status=signed&Email=test%2Bhosted%40twilio.com&PageSize=50&Page=0",

4
    "key": "items",

5
    "next_page_url": null,

6
    "page": 0,

7
    "page_size": 50,

8
    "previous_page_url": null,

9
    "url": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments?Status=signed&Email=test%2Bhosted%40twilio.com&PageSize=50&Page=0"

10
  },

11
  "items": []

12
}

Update an AuthorizationDocument resource

update-an-authorizationdocument-resource page anchor

POST https://preview.twilio.com/HostedNumbers/AuthorizationDocuments/{Sid}

Requests to update a single, existing Authorization Documents instance resource's properties and returns the updated resource representation if successful.

(warning)

Warning

The ability to update an Authorization Document will be removed once the API is released as a generally available (GA) product. You will be informed about the timeline and given time to update accordingly.

Authorization Documents can only be updated when in opened status. To update the Authorization Document, update the Status to opened.

Path parameters

path-parameters-1 page anchor
Property nameTypeRequiredPIIDescription
sidSID<PX>
required
Not PII

A 34 character string that uniquely identifies this AuthorizationDocument.

Pattern: ^PX[0-9a-fA-F]{32}$Min length: 34Max length: 34

Request body parameters

request-body-parameters-1 page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
hostedNumberOrderSidsarray[string]

Optional

Not PII

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

addressSidSID<AD>

Optional

Not PII

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

Pattern: ^AD[0-9a-fA-F]{32}$Min length: 34Max length: 34
emailstring

Optional

PII MTL: 30 days

Email that this AuthorizationDocument will be sent to for signing.

ccEmailsarray[string]

Optional

PII MTL: 30 days

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

statusenum<string>

Optional

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.

Possible values:
openedsigningsignedcanceledfailed
contactTitlestring

Optional

Not PII

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

contactPhoneNumberstring

Optional

Not PII

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

Update an AuthorizationDocumentLink to code sample: Update an AuthorizationDocument
1
// Download the helper library from https://www.twilio.com/docs/node/install

2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

3


4
// Find your Account SID and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function updateHostedNumbersAuthorizationDocument() {

11
  const authorizationDocument = await client.preview.hosted_numbers

12
    .authorizationDocuments("PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .update({ hostedNumberOrderSids: ["HostedNumberOrderSids"] });

14


15
  console.log(authorizationDocument.sid);

16
}

17


18
updateHostedNumbersAuthorizationDocument();

Response

1
{

2
  "address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "cc_emails": [

4
    "test1@twilio.com",

5
    "test2@twilio.com"

6
  ],

7
  "date_created": "2017-03-28T20:06:39Z",

8
  "date_updated": "2017-03-28T20:06:39Z",

9
  "email": "test+hosted@twilio.com",

10
  "links": {

11
    "dependent_hosted_number_orders": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments/PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/DependentHostedNumberOrders"

12
  },

13
  "sid": "PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

14
  "status": "signing",

15
  "url": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments/PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"

16
}