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

Bundles 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 Twilio Bundles REST API allows you to create empty Regulatory Bundle containers. The Regulatory Bundles are Item Assignments of End-Users and Supporting Documents for regulatory compliance.

Depending on the configuration of the bundle, the bundle is being assessed against a Regulation (e.g., Germany local phone numbers for a business). Different Regulations need Item Assignments combinations of End-User Types and Supporting Document Types.

Bundles Response Properties

bundles-response-properties page anchor

The field of the Bundle resource response is in JSON. The type SID<BU> is a unique ID starting with letters BU. For more information about Twilio SIDs, please refer to Twilio's glossary on SIDs.

Property nameTypeRequiredDescriptionChild properties
sidSID<BU>

Optional

Not PII

The unique string that we created to identify the Bundle resource.

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

Optional

Not PII

The SID of the Account that created the Bundle resource.

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

Optional

Not PII

The unique string of a regulation that is associated to the Bundle resource.

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

Optional

Not PII

The string that you assigned to describe the resource.

statusenum<string>

Optional

Not PII

The verification status of the Bundle resource.

Possible values:
draftpending-reviewin-reviewtwilio-rejectedtwilio-approvedprovisionally-approved
validUntilstring<date-time>

Optional

Not PII

The date and time in GMT in ISO 8601(link takes you to an external page) format when the resource will be valid until.

emailstring

Optional

Not PII

The email address that will receive updates when the Bundle resource changes status.

statusCallbackstring<uri>

Optional

Not PII

The URL we call to inform your application of status changes.

dateCreatedstring<date-time>

Optional

Not PII

The date and time in GMT when the resource was created specified in ISO 8601(link takes you to an external page) format.

dateUpdatedstring<date-time>

Optional

Not PII

The date and time in GMT when the resource was last updated specified in ISO 8601(link takes you to an external page) format.

urlstring<uri>

Optional

Not PII

The absolute URL of the Bundle resource.

linksobject<uri-map>

Optional

Not PII

The URLs of the Assigned Items of the Bundle resource.

Bundle Statuses

bundle-statuses page anchor

The following statuses encompass the Bundle lifecycle.

StatusDescription
draftThe user has created a new Bundle that can be edited with Supporting Documents and End-User objects assigned.
pending-reviewWhen the user has finished the draft of the Bundle and submits to Twilio for review, the status moves from draft to pending-review.
in-reviewTwilio has moved the Bundle from pending-review to in-review. Once Twilio has finished review, the Bundle will go either to twilio-approved or twilio-rejected.
twilio-rejectedTwilio has reviewed the Bundle and has determined the Bundle does not meet the regulations.
twilio-approvedTwilio has reviewed the Bundle and has determined the Bundles does meet the regulations.

Status Callback

status-callback page anchor

Every time the Bundle resource's status changes (except for when it changes from pending-review to in_review), Twilio sends a POST request to the URL specified in the Bundle's statusCallback property. The Content-Type of the request is application/x-www-form-urlencoded.

FieldDescription
AccountSIDThe SID of the Account that created the Bundle resource.
BundleSIDThe unique string that we created to identify the Bundle resource.
StatusThe verification status of the Bundle resource. See Bundle Statuses for a list of possible values.
FailureReasonThe description(s) of what incorrect configuration the Regulatory Bundle currently has.

Create a Bundle

create-a-bundle page anchor

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

To provision or port a phone number to Twilio, you will need to create a new Bundle that will contain all the information required to follow local telco Regulations.

The Bundle is a container that references the required Regulatory Compliance information set forth by the regulating telecom body of the end-user who actually answers the phone call or receives the message.

When creating the Bundle, you will specify the following parameters IsoCountry, NumberType, and EndUserType so you can follow compliance for a Regulation.

Request body parameters

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

The string that you assigned to describe the resource.

emailstring
required
Not PII

The email address that will receive updates when the Bundle resource changes status.

statusCallbackstring<uri>

Optional

Not PII

The URL we call to inform your application of status changes.

regulationSidSID<RN>

Optional

Not PII

The unique string of a regulation that is associated to the Bundle resource.

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

Optional

Not PII

The ISO country code(link takes you to an external page) of the Bundle's phone number country ownership request.

endUserTypeenum<string>

Optional

Not PII
Possible values:
individualbusiness
numberTypestring

Optional

Not PII

The type of phone number of the Bundle's ownership request. Can be local, mobile, national, or toll-free.

isTestboolean

Optional

Not PII

Indicates that Bundle is a Test Bundle and will be Auto-Rejected

Create a new BundleLink to code sample: Create a new Bundle
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 createBundle() {

11
  const bundle = await client.numbers.v2.regulatoryCompliance.bundles.create({

12
    email: "numbers-regulatory-review@twilio.com",

13
    endUserType: "business",

14
    friendlyName: "Twilio, Inc. DE Local Bundle",

15
    isoCountry: "de",

16
    numberType: "local",

17
    statusCallback: "https://twilio.status.callback.com",

18
  });

19


20
  console.log(bundle.sid);

21
}

22


23
createBundle();

Response

1
{

2
  "sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "regulation_sid": "RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "friendly_name": "Twilio, Inc. DE Local Bundle",

6
  "status": "draft",

7
  "email": "numbers-regulatory-review@twilio.com",

8
  "status_callback": "https://twilio.status.callback.com",

9
  "valid_until": null,

10
  "date_created": "2019-07-30T22:29:24Z",

11
  "date_updated": "2019-07-31T01:09:00Z",

12
  "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

13
  "links": {

14
    "evaluations": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Evaluations",

15
    "item_assignments": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ItemAssignments",

16
    "bundle_copies": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Copies"

17
  }

18
}

Fetch a Bundle Instance

fetch-a-bundle-instance page anchor

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

Path parameters

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

The unique string that we created to identify the Bundle resource.

Pattern: ^BU[0-9a-fA-F]{32}$Min length: 34Max length: 34
Fetch a Bundle instanceLink to code sample: Fetch a Bundle instance
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 fetchBundle() {

11
  const bundle = await client.numbers.v2.regulatoryCompliance

12
    .bundles("BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .fetch();

14


15
  console.log(bundle.sid);

16
}

17


18
fetchBundle();

Response

1
{

2
  "sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "regulation_sid": "RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "friendly_name": "friendly_name",

6
  "status": "draft",

7
  "valid_until": null,

8
  "email": "email",

9
  "status_callback": "http://www.example.com",

10
  "date_created": "2019-07-30T22:29:24Z",

11
  "date_updated": "2019-07-31T01:09:00Z",

12
  "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

13
  "links": {

14
    "evaluations": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Evaluations",

15
    "item_assignments": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ItemAssignments",

16
    "bundle_copies": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Copies"

17
  }

18
}

List all Bundles

list-all-bundles page anchor

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

If your application requires local inbound connectivity in many number types within a country or with many countries, you will have to create many Regulatory Bundle containers with all necessary information.

Query parameters

query-parameters page anchor
Property nameTypeRequiredPIIDescription
statusenum<string>

Optional

Not PII

The verification status of the Bundle resource. Please refer to Bundle Statuses for more details.

Possible values:
draftpending-reviewin-reviewtwilio-rejectedtwilio-approvedprovisionally-approved
friendlyNamestring

Optional

Not PII

The string that you assigned to describe the resource. The column can contain 255 variable characters.

regulationSidSID<RN>

Optional

Not PII

The unique string of a Regulation resource that is associated to the Bundle resource.

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

Optional

Not PII

The 2-digit ISO country code(link takes you to an external page) of the Bundle's phone number country ownership request.

numberTypestring

Optional

Not PII

The type of phone number of the Bundle's ownership request. Can be local, mobile, national, or toll-free.

hasValidUntilDateboolean

Optional

Not PII

Indicates that the Bundle is a valid Bundle until a specified expiration date.

sortByenum<string>

Optional

Not PII

Can be valid-until or date-updated. Defaults to date-created.

Possible values:
valid-untildate-updated
sortDirectionenum<string>

Optional

Not PII

Default is DESC. Can be ASC or DESC.

Possible values:
ASCDESC
validUntilDatestring<date-time>

Optional

Not PII

Date to filter Bundles having their valid_until_date before or after the specified date. Can be ValidUntilDate>= or ValidUntilDate<=. Both can be used in conjunction as well. ISO 8601(link takes you to an external page) is the acceptable date format.

validUntilDateBeforestring<date-time>

Optional

Not PII

Date to filter Bundles having their valid_until_date before or after the specified date. Can be ValidUntilDate>= or ValidUntilDate<=. Both can be used in conjunction as well. ISO 8601(link takes you to an external page) is the acceptable date format.

validUntilDateAfterstring<date-time>

Optional

Not PII

Date to filter Bundles having their valid_until_date before or after the specified date. Can be ValidUntilDate>= or ValidUntilDate<=. Both can be used in conjunction as well. ISO 8601(link takes you to an external page) is the acceptable date format.

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 all BundlesLink to code sample: List all Bundles
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 listBundle() {

11
  const bundles = await client.numbers.v2.regulatoryCompliance.bundles.list({

12
    limit: 20,

13
  });

14


15
  bundles.forEach((b) => console.log(b.sid));

16
}

17


18
listBundle();

Response

1
{

2
  "results": [],

3
  "meta": {

4
    "page": 0,

5
    "page_size": 50,

6
    "first_page_url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles?PageSize=50&Page=0",

7
    "previous_page_url": null,

8
    "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles?PageSize=50&Page=0",

9
    "next_page_url": null,

10
    "key": "results"

11
  }

12
}

Update a Bundle instance

update-a-bundle-instance page anchor

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

Path parameters

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

The unique string that we created to identify the Bundle resource.

Pattern: ^BU[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
statusenum<string>

Optional

Not PII

The verification status of the Bundle resource.

Possible values:
draftpending-reviewin-reviewtwilio-rejectedtwilio-approvedprovisionally-approved
statusCallbackstring<uri>

Optional

Not PII

The URL we call to inform your application of status changes.

friendlyNamestring

Optional

Not PII

The string that you assigned to describe the resource.

emailstring

Optional

Not PII

The email address that will receive updates when the Bundle resource changes status.

Update a Bundle instanceLink to code sample: Update a Bundle instance
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 updateBundle() {

11
  const bundle = await client.numbers.v2.regulatoryCompliance

12
    .bundles("BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")

13
    .update({

14
      friendlyName: "UpdatedSubmitedFriendlyName",

15
      status: "pending-review",

16
    });

17


18
  console.log(bundle.sid);

19
}

20


21
updateBundle();

Response

1
{

2
  "sid": "BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

3
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

4
  "regulation_sid": "RNaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

5
  "friendly_name": "UpdatedSubmitedFriendlyName",

6
  "status": "pending-review",

7
  "email": "email",

8
  "status_callback": "http://www.example.com",

9
  "valid_until": null,

10
  "date_created": "2019-07-30T22:29:24Z",

11
  "date_updated": "2019-07-31T01:09:00Z",

12
  "url": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",

13
  "links": {

14
    "evaluations": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Evaluations",

15
    "item_assignments": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ItemAssignments",

16
    "bundle_copies": "https://numbers.twilio.com/v2/RegulatoryCompliance/Bundles/BUaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Copies"

17
  }

18
}

Delete a Bundle instance

delete-a-bundle-instance page anchor

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

The DELETE operation is allowed for Regulatory Bundles with status of DRAFT, TWILIO_APPROVED, or TWILIO_REJECTED and have no active Long Code phone number assignments.

Path parameters

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

The unique string that we created to identify the Bundle resource.

Pattern: ^BU[0-9a-fA-F]{32}$Min length: 34Max length: 34
Delete a Bundle InstanceLink to code sample: Delete a Bundle Instance
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 deleteBundle() {

11
  await client.numbers.v2.regulatoryCompliance

12
    .bundles("BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")

13
    .remove();

14
}

15


16
deleteBundle();