Destinations API quickstart

(new)

Beta

Data Destinations is currently available as a Private Beta product and the information contained in this document is subject to change. Data Destinations is not a HIPAA Eligible Service or PCI compliant and should not be enabled in workflows that are subject to HIPAA or PCI. To learn more, see Private beta legal information.

Use the Destination API to manage Twilio Subscriptions and Destinations.

This page outlines how to authenticate and get started with the Destinations API. You'll also learn about some key Data Destination concepts.

(information)

Want full access to the Destinations API?

To learn more about the Destinations API, join the Data Destinations private beta.

Authentication

Twilio supports HTTP Basic authentication. Include the Basic Authentication header, using your API key SID as the username and your API key secret as the password. If you're no longer using a key, revoke it to prevent unauthorized access.

See our Twilio API requests documentation to learn more about using Twilio APIs.

Using the Destinations API

You can use the following APIs to get started with Data Destinations:

After you complete these steps, Twilio routes internal events downstream to your third-party business tool.

The following methods help you manage your resources:

(information)

Info

If you prefer getting started with Data Destinations in Console, see Set up a data destination.

Create a destination

To get started with Data Destinations, you first need to create a destination. A destination is a third-party business tool that can recieve your Twilio event data.

You can create up to 200 destinations per account. Any destinations that exceed this limit result in a 409 Conflict error.

Create a destination

POST "https://destinations.twilio.com/v1/ControlPlane/Destinations"

Request body schema

Name	Type	Required	Description
`destinationType`	string	Yes	Destination type identifier from the catalog. If you don't know the `destinationType`, send a `GET` request to `/v1/Catalog/DestinationTypes` and match against each entry's name and description.
`name`	string	Yes	The name of this destination, up to 128 characters.
`config`	object	No	Use the reserved `credentials` key to supply authentication credentials, when that destination type's `configOptions` declares one.
`status`	enum`<string>`	No	Either `ENABLED`, if you want to begin validation and activate the destination, or `DISABLED`. `ENABLED` is the default value.

Create a subscription

Once you've created a destination, you'll create a subscription. By creating a subsciption, you'll select the events you'd like to send downstream to your business tools.

You can create up to 200 subscriptions in your Twilio account. Any subscriptions that exceed this limit result in a 409 Conflict error.

Create a subscription

POST "https://destinations.twilio.com/v1/ControlPlane/Subscriptions"

Request body schema

Name	Type	Description
description (Required)	string	A human readable description of this subscription, up to 128 characters.
destinationId (Required)	string	The ID of the destination that you created and would like to send events to.
eventTypes (Required)	array`[object]`	An array of the event types you'd like to subscribe to.
status	enum`<string>`	Either `ENABLED`, if you want to activate the subscription, or `DISABLED`, if you'd like to create a subscription that doesn't receive events.

Update a subscription

Update an existing subscription. You can change the description and status synchronously (returns 200). When you provide eventTypes, Twilio replaces the event list asynchronously. This operation returns 202 and a statusUrl to poll for completion.

Update a subscription

PATCH "https://destinations.twilio.com/v1/ControlPlane/Subscriptions/{subscriptionId}"

Path parameters

Name	Type	Description
subscriptionId (Required)	string	The Unique ID for the subscription.

Request body

Name	Type	Description
description	string	The human-readable description of the subscription.
status	enum`<string>`	The status of the subscription, either `ENABLED` or `DISABLED`.
eventTypes	array`[object]`	Replacement list of event types for the Subscription. Any event types that have the same `eventType` and `schemaVersion` preserve their existing binding configuration. Twilio provisions new entries asynchronously.

Fetch operation status

Retrieve the status of an asynchronous operation. Poll this endpoint using the statusUrl returned from the initiating request. The Retry-After response header indicates the recommended polling interval. Once the operation reaches a terminal status (COMPLETED, CANCELLED, or FAILED), the Retry-After header is no longer present.

When status is COMPLETED, the resultUrl field points to the created or updated resource. When status is FAILED, the error field contains details.

Fetch operation status

GET "https://destinations.twilio.com/v1/ControlPlane/Operations/{operationId}"

Path parameters

Name	Type	Description
operationId (Required)	string	The unique identifier of this operation.

List all destinations

Retrieve a list of all destinations for the authenticated account. Results are paginated.

List all destinations

GET "https://destinations.twilio.com/v1/ControlPlane/Destinations"

Query parameters

Name	Type	Description
pageSize	integer	The maximum number of items Twilio should return per page. The maximum is 100.
pageToken	string	The token for the page of results to retrieve.
orderBy	enum`<string>`	Either `ASC` or `DESC` to sort results ascending or descending, respectively.
namePrefix	string	Case-insensitive prefix match on the destination name. Omit the parameter to disable filtering. Send at least one character when the parameter is present. Twilio trims leading or trailing whitespace server-side.

List all subscriptions

Retrieve a list of all subscriptions for the authenticated account. Results are paginated.

Query paramters

Name	Type	Description
pageSize	integer	The maximum number of items Twilio should return per page. The maximum is 100.
pageToken	string	The token for the page of results to retrieve.
orderBy	enum`<string>`	Either `ASC` or `DESC` to sort results ascending or descending, respectively.
destinationId	string	Filter by Destination ID.
eventTypePrefix	string	Filter to Subscriptions that contain at least one subscribed event type matching the given prefix. For example, `com.twilio.messaging` matches any `com.twilio.messaging.*` event type.