Skip to content Skip to navigation Skip to topbar

On this page

Supporting Documents Resource

(warning)

Warning

The v2 Regulatory Compliance APIs are currently in Public Beta. No breaking changes in the API contract will occur when the API moves from Public Beta to GA.

The Supporting Documents resource of Twilio's Regulatory Compliance APIs allows you to create new Supporting Documents with metadata to fulfill Regulations. Each Supporting Document Type may need different information to be compliant, so be sure to pass all of the correct values when creating a new Supporting Document Type.

A collection of Supporting Documents Assigned as Items to a Regulatory Bundle along with an End-User satisfies a Regulation.

Supporting Documents Response Properties

The field of the Supporting Documents resource responds is in JSON. The type SID<RD> is a unique ID starting with letters RD that reference a unique Supporting Document instance. For more information about Twilio SIDs, please refer to Twilio's glossary on SIDs.

Property nameTypePIIDescription

sidSID<RD>

The unique string created by Twilio to identify the Supporting Document resource.

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

account_sidSID<AC>

The SID of the Account that created the Document resource.

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

friendly_namestring

The string that you assigned to describe the resource.

mime_typestring

The image type uploaded in the Supporting Document container.

statusenum<string>

The verification status of the Supporting Document resource.

Possible values:

draftpending-reviewrejectedapprovedexpiredprovisionally-approved

failure_reasonstring

The failure reason of the Supporting Document Resource.

typestring

The type of the Supporting Document.

attributesobject

PII MTL: 30 days

The set of parameters that are the attributes of the Supporting Documents resource which are listed in the Supporting Document Types.

date_createdstring<date-time>

The date and time in GMT when the resource was created specified in ISO 8601 format.

date_updatedstring<date-time>

The date and time in GMT when the resource was last updated specified in ISO 8601 format.

urlstring<uri>

The absolute URL of the Supporting Document resource.

Supporting Document Statuses

The following statuses encompass the Bundle lifecycle.

Status	Description
draft	The draft status of the Supporting Document allows users to edit the Supporting Document file and metadata.
pending-review	When the user has finished the draft and submits the Supporting Document for review, the status moves from `draft` to `pending-review`, awaiting Twilio's.
rejected	Twilio has reviewed the Supporting Document and has determined the Supporting Document does not comply with the regulations.
approved	Twilio has reviewed the Supporting Document and has determined the Supporting Document does not comply with the regulations.
expired	The document has expired and is no longer valid to provision phone numbers. An updated document must be created and added to a new or existing Bundle.

Create a Supporting Document

POST https://numbers.twilio.com/v2/RegulatoryCompliance/SupportingDocuments

To provision or port in a phone number to Twilio, you will need to create one or many Supporting Documents that also may need an image as proof.

A Supporting Document is a container that holds metadata of a legal document. Each Supporting Document Type requires a different value during the create operation.

The Regulation may need the End-User to upload an image as proof for the Supporting Document. Formats accepted are JPEG, PNG, and PDF, with a file size limit of 5 MB.

Request body parameters

Property nameTypeRequiredPIIDescription

FriendlyNamestringrequired

The string that you assigned to describe the resource.

Typestringrequired

The type of the Supporting Document.

AttributesobjectOptional

PII MTL: 30 days

The set of parameters that are the attributes of the Supporting Documents resource which are derived Supporting Document Types.

Create a Supporting Document

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


_26// Download the helper library from https://www.twilio.com/docs/node/install
_26const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_26
_26// Find your Account SID and Auth Token at twilio.com/console
_26// and set the environment variables. See http://twil.io/secure
_26const accountSid = process.env.TWILIO_ACCOUNT_SID;
_26const authToken = process.env.TWILIO_AUTH_TOKEN;
_26const client = twilio(accountSid, authToken);
_26
_26async function createSupportingDocument() {
_26  const supportingDocument =
_26    await client.numbers.v2.regulatoryCompliance.supportingDocuments.create({
_26      attributes: {
_26        address_sids: [
_26          "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26          "ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_26        ],
_26      },
_26      friendlyName: "BusinessRegistration",
_26      type: "business_registration",
_26    });
_26
_26  console.log(supportingDocument.sid);
_26}
_26
_26createSupportingDocument();

Output


_16{
_16  "sid": "RDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16  "friendly_name": "BusinessRegistration",
_16  "mime_type": "mime_type",
_16  "status": "draft",
_16  "failure_reason": null,
_16  "type": "business_registration",
_16  "attributes": {
_16    "first_name": "foo",
_16    "last_name": "bar"
_16  },
_16  "date_created": "2019-07-31T02:11:52Z",
_16  "date_updated": "2019-07-31T02:11:52Z",
_16  "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/SupportingDocuments/RDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_16}

Create a Supporting Document and upload a file

curl


_16ATTRIBUTES=$(cat << EOF
_16{
_16    "address_sids": ["ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"],
_16    "document_number": "312454", 
_16    "business_name": "Twilio",
_16    "issue_date": "2019-11-15"
_16}
_16EOF
_16)
_16
_16curl -X POST https://numbers-upload.twilio.com/v2/RegulatoryCompliance/SupportingDocuments \
_16-F "Attributes=$ATTRIBUTES" \
_16-F "FriendlyName=Twilio GmbH" \
_16-F "Type=business_registration" \
_16-F "File=@twilio_business_registration.png" \
_16-u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token

Output


_17{
_17    "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17    "attributes": {
_17        "business_name": "Twilio",
_17        "document_number": "312454",
_17        "issue_date": "2019-11-15",
_17        "registered_seat_of_business": "San Francisco, CA, USA"
_17    },
_17    "date_created": "2019-10-17T17:06:47Z",
_17    "date_updated": "2019-10-17T17:06:47Z",
_17    "friendly_name": "Twilio GmbH",
_17    "mime_type": "image/png",
_17    "sid": "RDd6340f49f352d06b77e7017d93591483",
_17    "status": "draft",
_17    "type": "business_registration",
_17    "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Documents/RDd6340f49f352d06b77e7017d93591483"
_17}

Fetch a Supporting Document instance

GET https://numbers.twilio.com/v2/RegulatoryCompliance/SupportingDocuments/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

SidSID<RD>required

The unique string created by Twilio to identify the Supporting Document resource.

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

Fetch a Supporting Document instance

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

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 fetchSupportingDocument() {
_18  const supportingDocument = await client.numbers.v2.regulatoryCompliance
_18    .supportingDocuments("RDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_18    .fetch();
_18
_18  console.log(supportingDocument.sid);
_18}
_18
_18fetchSupportingDocument();

Output


_16{
_16  "sid": "RDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16  "friendly_name": "friendly_name",
_16  "mime_type": "mime_type",
_16  "status": "draft",
_16  "failure_reason": null,
_16  "type": "type",
_16  "attributes": {
_16    "first_name": "foo",
_16    "last_name": "bar"
_16  },
_16  "date_created": "2019-07-31T02:11:52Z",
_16  "date_updated": "2019-07-31T02:11:52Z",
_16  "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/SupportingDocuments/RDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_16}

Retrieve a list of Supporting Documents

GET https://numbers.twilio.com/v2/RegulatoryCompliance/SupportingDocuments

Query parameters

Property nameTypeRequiredPIIDescription

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.

Retrieve a list of Supporting Documents

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

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 listSupportingDocument() {
_19  const supportingDocuments =
_19    await client.numbers.v2.regulatoryCompliance.supportingDocuments.list({
_19      limit: 20,
_19    });
_19
_19  supportingDocuments.forEach((s) => console.log(s.sid));
_19}
_19
_19listSupportingDocument();

Output


_12{
_12  "results": [],
_12  "meta": {
_12    "page": 0,
_12    "page_size": 50,
_12    "first_page_url": "https://numbers.twilio.com/v2/RegulatoryCompliance/SupportingDocuments?PageSize=50&Page=0",
_12    "previous_page_url": null,
_12    "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/SupportingDocuments?PageSize=50&Page=0",
_12    "next_page_url": null,
_12    "key": "results"
_12  }
_12}

Update a Supporting Document Instance

POST https://numbers.twilio.com/v2/RegulatoryCompliance/SupportingDocuments/{Sid}

Path parameters

Property nameTypeRequiredPIIDescription

SidSID<RD>required

The unique string created by Twilio to identify the Supporting Document resource.

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

Request body parameters

Property nameTypeRequiredPIIDescription

FriendlyNamestringOptional

The string that you assigned to describe the resource.

AttributesobjectOptional

PII MTL: 30 days

The set of parameters that are the attributes of the Supporting Document resource which are derived Supporting Document Types.

Update a Supporting Document instance

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

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 updateSupportingDocument() {
_18  const supportingDocument = await client.numbers.v2.regulatoryCompliance
_18    .supportingDocuments("RDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
_18    .update({ friendlyName: "My new Friendly Name" });
_18
_18  console.log(supportingDocument.sid);
_18}
_18
_18updateSupportingDocument();

Output


_16{
_16  "sid": "RDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_16  "friendly_name": "My new Friendly Name",
_16  "mime_type": "mime_type",
_16  "status": "draft",
_16  "failure_reason": null,
_16  "type": "type",
_16  "attributes": {
_16    "first_name": "foo",
_16    "last_name": "bar"
_16  },
_16  "date_created": "2019-07-31T02:11:52Z",
_16  "date_updated": "2019-07-31T02:11:52Z",
_16  "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/SupportingDocuments/RDaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
_16}

Delete a Supporting Document instance

DELETE https://numbers.twilio.com/v2/RegulatoryCompliance/SupportingDocuments/{Sid}

The DELETE operation is allowed for Supporting Documents with status of DRAFT, APPROVED, or REJECTED and have no active Long Code phone number assignments.

Path parameters

Property nameTypeRequiredPIIDescription

SidSID<RD>required

The unique string created by Twilio to identify the Supporting Document resource.

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

Delete a Supporting Document instance

Node.js

Python

C#

Java

Go

PHP

Ruby

twilio-cli

curl


_16// Download the helper library from https://www.twilio.com/docs/node/install
_16const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
_16
_16// Find your Account SID and Auth Token at twilio.com/console
_16// and set the environment variables. See http://twil.io/secure
_16const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16const authToken = process.env.TWILIO_AUTH_TOKEN;
_16const client = twilio(accountSid, authToken);
_16
_16async function deleteSupportingDocument() {
_16  await client.numbers.v2.regulatoryCompliance
_16    .supportingDocuments("RDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
_16    .remove();
_16}
_16
_16deleteSupportingDocument();