Consent Management API

(information)

Public Beta

The Consent Management API is in Public Beta and is available globally to all Twilio Programmable Messaging customers. It supports cross-channel consent synchronization across RCS, SMS, and MMS channels.

Customers using Twilio's Compliance Toolkit obtain default access to the API.

This Public Beta is available for early adopter customers to test and provide feedback. To request access, reach out to Twilio Support or contact your sales representative for more information on enablement and pricing.

Consent Management API is available in Public Beta and the information contained in this document is subject to change. Some features are not yet implemented and others may be changed before the product is declared as Generally Available. Beta products are not covered by the Twilio Support Terms or the Twilio Service Level Agreement.

(warning)

Note

Consent Management API is not a HIPAA Eligible Service and should not be used in workflows that are subject to HIPAA.

Twilio's Consent Management API lets you bulk manage user consent preferences globally across your messaging channels. Use it to store, sync, or update opt-in, opt-out, and re-opt-in statuses for your users across RCS, SMS, and MMS channels, along with details about how and when consent was collected.

With this API, you can manage the following user consent states across RCS, SMS, and MMS channels:

Consent status	Description
`opt in`	The user has provided valid consent to receive messages.
`opt out`	The user has revoked consent or replied with STOP-like keywords. This blocks future messages.
`re-opt in`	Handled as opt-in. The user has opted in again after a prior opt-out. Overrides STOP keyword to resume messaging.

Rate limits

Twilio limits the Consent Management API to 100 requests per minute. Once you reach this limit, the API returns an HTTP 429 "Too Many Requests" response. If you need support for higher rate limits, contact Twilio Support.

Timeouts

Consent Management API has a timeout value of three seconds.

Upsert Consents in Bulk

POST https://accounts.twilio.com/v1/Consents/Bulk

Creates up to 25 consents for an authenticated account. If a consent already exists, it will be updated (via upsert) to match the requested object.

Every Consent object should be associated with a unique correlation_id, allowing you to track each individual request within the bulk operation.

If any issues arise during the processing of a consent object, an error will be returned and mapped specifically to that consent's correlation_id. This allows you to pinpoint and address issues for individual contacts.

For detailed information on possible failures and how to resolve them, refer to error code 30646, which provides guidance on common errors such as incorrect phone number format, missing required fields, and other validation issues.

Request body parameters

Encoding type:application/x-www-form-urlencoded

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

itemsarray

required

PII MTL: 30 days

This is a list of objects that describes a contact's opt-in status. Each object contains the following fields: contact_id, which must be a string representing phone number in E.164 format; correlation_id, a unique 32-character UUID used to uniquely map the request item with the response item; sender_id, which can be either a valid messaging service SID or a from phone number; status, a string representing the consent status. Can be one of [opt-in, opt-out]; source, a string indicating the medium through which the consent was collected. Can be one of [website, offline, opt-in-message, opt-out-message, others]; date_of_consent, an optional datetime string field in ISO-8601 format that captures the exact date and time when the user gave or revoked consent. If not provided, it will be empty.

Upsert Consents in Bulk

1// Download the helper library from https://www.twilio.com/docs/node/install
2const 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
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createBulkConsents() {
11  const bulkConsent = await client.accounts.v1.bulkConsents.create({
12    items: [
13      {
14        contact_id: "+19999999991",
15        correlation_id: "ad388b5a46b33b874b0d41f7226db2ef",
16        sender_id: "MG00000000000000000000000000000000",
17        date_of_consent: "2025-02-28T10:05:27Z",
18        status: "opt-in",
19        source: "website",
20      },
21      {
22        contact_id: "+447700900077",
23        correlation_id: "02520cfa6c432f0e3ec3a38c122d428d",
24        sender_id: "+12345678901",
25        date_of_consent: "2025-02-25T14:30:00Z",
26        status: "opt-out",
27        source: "opt-out-message",
28      },
29      {
30        contact_id: "+173800900067",
31        correlation_id: "8u344b9a46b33b874b0d41f7776hb72f",
32        sender_id: "rcs:test_-_twilio_4n2azqfk_agent",
33        date_of_consent: "2025-02-25T14:30:00Z",
34        status: "opt-out",
35        source: "offline",
36      },
37    ],
38  });
39
40  console.log(bulkConsent.items);
41}
42
43createBulkConsents();

Response

1{
2  "items": [
3    {
4      "contact_id": "+19999999991",
5      "correlation_id": "ad388b5a46b33b874b0d41f7226db2ef",
6      "sender_id": "MG00000000000000000000000000000000",
7      "date_of_consent": "2025-02-28T10:05:27Z",
8      "status": "opt-in",
9      "source": "website"
10    },
11    {
12      "contact_id": "+447700900077",
13      "correlation_id": "02520cfa6c432f0e3ec3a38c122d428d",
14      "sender_id": "+12345678901",
15      "date_of_consent": "2025-02-25T14:30:00Z",
16      "status": "opt-out",
17      "source": "opt-out-message"
18    },
19    {
20      "contact_id": "+173800900067",
21      "correlation_id": "8u344b9a46b33b874b0d41f7776hb72f",
22      "sender_id": "rcs:test_-_twilio_4n2azqfk_agent",
23      "date_of_consent": "2025-02-25T14:30:00Z",
24      "status": "opt-out",
25      "source": "offline"
26    }
27  ]
28}

Each item in the response matches the submitted correlation_id. This enables tracing of validation errors for specific contacts.

Note: STOP keyword override applies to all messages sent, except US Toll-free numbers. Toll-free opt out handling is managed at the network level in the US.

Best practices

Use a Messaging Service SID (MGXX...) as your sender_id to ensure consent and opt-outs are seamlessly synchronized across RCS, SMS, and MMS channels.
Always use a unique correlation_id per contact update.
Store and update the date_of_consent to establish proper consent timelines.
Use status=opt-in with source to update re-opt-in consent records.
Ensure contact_id is in proper E.164 format.

Consent Management API

Public Beta

Note

Supported consent preferences

Rate limits

Timeouts