Consent Management API

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

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.

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.

Consent Management API has a timeout value of three seconds.

These properties are returned in the JSON response.

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.

{
  "Items": [
    "{\"contact_id\":\"+19999999999\",\"correlation_id\":\"ad388b5a46b33b874b0d41f7226db2ef\",\"sender_id\":\"MG00000000000000000000000000000001\",\"date_of_consent\":\"2025-02-28T10:05:27Z\",\"status\":\"opt-out\",\"source\":\"website\"}",
    "{\"contact_id\":\"+19\",\"correlation_id\":\"02520cfa6c432f0e3ec3a38c122d428d\",\"sender_id\":\"123456\",\"date_of_consent\":\"2025-03-25\",\"status\":\"opt-in\",\"source\":\"opt-in-message\"}"
  ]
}

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 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

43
createBulkConsents();

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.

When a user replies with a standard opt-out keyword (such as STOP) to a message sent through a Twilio Messaging Service, Twilio automatically creates two distinct opt-out records to ensure compliance:

• An opt-out at the Messaging Service level.
• An opt-out at the individual Sender level (the specific Twilio phone number that delivered the message).

While these records exist, any subsequent message attempt to this user fails and returns Error 21610.

If the user later provides valid consent to receive messages again (re-opt-in), you must clear both of these underlying opt-out records. To successfully process a re-opt-in and resume messaging, submit two separate opt-in entries using the Consent Management API.

To restore the user's consent status, execute a request containing the following two updates for the destination number:

• Create an opt-in record using your Messaging Service SID (for example, MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX) as the sender_id. This clears the Messaging Service level block.
• Create a second opt-in record using the specific From phone number (for example, +1234567XXXX) as the sender_id. This clears the Sender level block.

Once both opt-in entries are successfully processed by the API, Twilio's opt-out blocks are lifted, and your application can immediately resume successful message delivery to the user.

• 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 the contact_id is always passed in proper E.164 format.