--- "@context": https://schema.org "@type": TechArticle "@id": https://www.twilio.com/docs/data-destinations/api-quickstart#article headline: Destinations API quickstart description: Learn more about authenticating with and using the Destinations API. url: https://www.twilio.com/docs/data-destinations/api-quickstart inLanguage: en dateModified: 2026-11-04T17:24:28.000Z author: "@type": Organization name: Twilio Developer Education Team publisher: "@type": Organization name: Twilio --- # Destinations API quickstart > \[!IMPORTANT] > > 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](/docs/data-destinations#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. > \[!NOTE] > > To learn more about the Destinations API, [join the Data Destinations private beta](https://airtable.com/appaJfyV6LiIFMxuP/pagIaOAtKsQVxTfdW/form). ## 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](/docs/usage/requests-to-twilio) documentation to learn more about using Twilio APIs. ## Using the Destinations API You can use the following APIs to get started with Data Destinations: 1. [Create a destination](#create-a-destination) 2. [Create a subscription](#create-a-subscription) After you complete these steps, Twilio routes internal events downstream to your third-party business tool. The following methods help you manage your resources: * [Update a Subscription](#update-a-subscription) * [Fetch operation status](#fetch-operation-status) * [List all destinations for an account](#list-all-destinations) * [List all subscriptions for an account](#list-all-subscriptions) > \[!NOTE] > > If you prefer getting started with Data Destinations in Console, see [Set up a data destination](/docs/data-destinations/destination-setup). ### 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. ```text title="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`` | 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. ```text title="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`` | 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. ```text title="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`` | 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. ```text title="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. ```text title="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`` | 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`` | 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. |