Skip to content Skip to navigation Skip to topbar

On this page

Authorization Document Resource

(error)

Danger

The Hosted Phone Numbers API is currently in development and not intended for use by new customers. This documentation exists to support customers who are already using the API. A new version of this API will be released as a generally available (GA) product in the near future. New customers should wait for the Hosted Phone Numbers GA release.

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

Property nameTypePIIDescription

sidSID<PX>

A 34 character string that uniquely identifies this AuthorizationDocument.

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

address_sidSID<AD>

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>

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

PII MTL: 30 days

Email that this AuthorizationDocument will be sent to for signing.

cc_emailsarray[string]

PII MTL: 30 days

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

date_createdstring<date-time>

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

date_updatedstring<date-time>

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

urlstring<uri>

linksobject<uri-map>

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.

Create an AuthorizationDocument resource

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

Property nameTypeRequiredPIIDescription

HostedNumberOrderSidsarray[string]required

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

AddressSidSID<AD>required

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

Emailstringrequired

PII MTL: 30 days

Email that this AuthorizationDocument will be sent to for signing.

ContactTitlestringrequired

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

ContactPhoneNumberstringrequired

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 AuthorizationDocument

Node.js

Python

C#

Java

PHP

Ruby

curl


_23// Download the helper library from https://www.twilio.com/docs/node/install
_23const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_23
_23// Find your Account SID and Auth Token at twilio.com/console
_23// and set the environment variables. See http://twil.io/secure
_23const accountSid = process.env.TWILIO_ACCOUNT_SID;
_23const authToken = process.env.TWILIO_AUTH_TOKEN;
_23const client = twilio(accountSid, authToken);
_23
_23async function createAuthorizationDocument() {
_23  const authorizationDocument =
_23    await client.preview.hosted_numbers.authorizationDocuments.create({
_23      addressSid: "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_23      contactPhoneNumber: "ContactPhoneNumber",
_23      contactTitle: "ContactTitle",
_23      email: "Email",
_23      hostedNumberOrderSids: ["HostedNumberOrderSids"],
_23    });
_23
_23  console.log(authorizationDocument.sid);
_23}
_23
_23createAuthorizationDocument();

Output


_16{
_16  "address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16  "cc_emails": [
_16    "test1@twilio.com",
_16    "test2@twilio.com"
_16  ],
_16  "date_created": "2017-03-28T20:06:39Z",
_16  "date_updated": "2017-03-28T20:06:39Z",
_16  "email": "Email",
_16  "links": {
_16    "dependent_hosted_number_orders": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments/PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/DependentHostedNumberOrders"
_16  },
_16  "sid": "PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16  "status": "signing",
_16  "url": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments/PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_16}

Fetch an AuthorizationDocument resource

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

Path parameters

Property nameTypeRequiredPIIDescription

SidSID<PX>required

A 34 character string that uniquely identifies this AuthorizationDocument.

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

Fetch an AuthorizationDocument

Node.js

Python

C#

Java

PHP

Ruby

curl


_18// Download the helper library from https://www.twilio.com/docs/node/install
_18const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18// Find your Account SID and Auth Token at twilio.com/console
_18// and set the environment variables. See http://twil.io/secure
_18const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18const authToken = process.env.TWILIO_AUTH_TOKEN;
_18const client = twilio(accountSid, authToken);
_18
_18async function fetchAuthorizationDocument() {
_18  const authorizationDocument = await client.preview.hosted_numbers
_18    .authorizationDocuments("PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_18    .fetch();
_18
_18  console.log(authorizationDocument.sid);
_18}
_18
_18fetchAuthorizationDocument();

Output


_16{
_16  "address_sid": "AD11111111111111111111111111111111",
_16  "cc_emails": [
_16    "aaa@twilio.com",
_16    "bbb@twilio.com"
_16  ],
_16  "date_created": "2017-03-28T20:06:39Z",
_16  "date_updated": "2017-03-28T20:06:39Z",
_16  "email": "test@twilio.com",
_16  "links": {
_16    "dependent_hosted_number_orders": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments/PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/DependentHostedNumberOrders"
_16  },
_16  "sid": "PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16  "status": "signing",
_16  "url": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments/PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_16}

Read multiple AuthorizationDocument resources

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

Query parameters

Property nameTypeRequiredPIIDescription

EmailstringOptional

Email that this AuthorizationDocument will be sent to for signing.

Statusenum<string>Optional

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

PageSizeintegerOptional

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

Minimum: 1Maximum: 1000

PageintegerOptional

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

Minimum: 0

PageTokenstringOptional

The page token. This is provided by the API.

List multiple AuthorizationDocuments

Node.js

Python

C#

Java

PHP

Ruby

curl


_19// Download the helper library from https://www.twilio.com/docs/node/install
_19const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_19
_19// Find your Account SID and Auth Token at twilio.com/console
_19// and set the environment variables. See http://twil.io/secure
_19const accountSid = process.env.TWILIO_ACCOUNT_SID;
_19const authToken = process.env.TWILIO_AUTH_TOKEN;
_19const client = twilio(accountSid, authToken);
_19
_19async function listAuthorizationDocument() {
_19  const authorizationDocuments =
_19    await client.preview.hosted_numbers.authorizationDocuments.list({
_19      limit: 20,
_19    });
_19
_19  authorizationDocuments.forEach((a) => console.log(a.sid));
_19}
_19
_19listAuthorizationDocument();

Output


_12{
_12  "meta": {
_12    "first_page_url": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments?Status=signed&Email=test%2Bhosted%40twilio.com&PageSize=50&Page=0",
_12    "key": "items",
_12    "next_page_url": null,
_12    "page": 0,
_12    "page_size": 50,
_12    "previous_page_url": null,
_12    "url": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments?Status=signed&Email=test%2Bhosted%40twilio.com&PageSize=50&Page=0"
_12  },
_12  "items": []
_12}

Update an AuthorizationDocument resource

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

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

Path parameters

Property nameTypeRequiredPIIDescription

SidSID<PX>required

A 34 character string that uniquely identifies this AuthorizationDocument.

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

Request body parameters

Property nameTypeRequiredPIIDescription

HostedNumberOrderSidsarray[string]Optional

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

AddressSidSID<AD>Optional

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

EmailstringOptional

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

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

ContactTitlestringOptional

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

ContactPhoneNumberstringOptional

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

Update an AuthorizationDocument

Node.js

Python

C#

Java

PHP

Ruby

curl


_18// Download the helper library from https://www.twilio.com/docs/node/install
_18const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_18
_18// Find your Account SID and Auth Token at twilio.com/console
_18// and set the environment variables. See http://twil.io/secure
_18const accountSid = process.env.TWILIO_ACCOUNT_SID;
_18const authToken = process.env.TWILIO_AUTH_TOKEN;
_18const client = twilio(accountSid, authToken);
_18
_18async function updateAuthorizationDocument() {
_18  const authorizationDocument = await client.preview.hosted_numbers
_18    .authorizationDocuments("PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_18    .update({ hostedNumberOrderSids: ["HostedNumberOrderSids"] });
_18
_18  console.log(authorizationDocument.sid);
_18}
_18
_18updateAuthorizationDocument();

Output


_16{
_16  "address_sid": "ADaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16  "cc_emails": [
_16    "test1@twilio.com",
_16    "test2@twilio.com"
_16  ],
_16  "date_created": "2017-03-28T20:06:39Z",
_16  "date_updated": "2017-03-28T20:06:39Z",
_16  "email": "test+hosted@twilio.com",
_16  "links": {
_16    "dependent_hosted_number_orders": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments/PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/DependentHostedNumberOrders"
_16  },
_16  "sid": "PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16  "status": "signing",
_16  "url": "https://preview.twilio.com/HostedNumbers/AuthorizationDocuments/PXaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_16}