Skip to contentSkip to navigationSkip to topbar
On this page

Bulk Upsert Consents


(information)

Bulk Upsert Consents API is now in Pilot.

This feature is currently in the Pilot maturity stage, which means that we're actively looking for early-adopter customers to try it out and give feedback. That could be you!

Bulk Upsert Consents API currently only supports the SMS channel.

(warning)

Not a HIPAA Eligible Service

Bulk Upsert Consents is not a HIPAA Eligible Service and should not be used in Bulk Upsert Consents workflows that are subject to HIPAA.

This API allows you to bulk upsert consents for multiple contacts. You can provide details such as contact_id, correlation_id, sender_id, status, and source to manage the opt-in/opt-out status of your contacts.


Rate limits

rate-limits page anchor

Bulk Upsert Consents API provides a built-in rate limit of 100 requests per minute. If you reach this limit, the API returns an HTTP 429 "Too Many Requests" response.


Bulk Upsert Consents API has a timeout value of three seconds. However, its 99th percentile is within 1 second.


Bulk Upsert Consents API Response Properties

bulk-upsert-consents-api-response-properties page anchor

These properties are returned in the JSON response.

Property nameTypeRequiredDescriptionChild properties
itemsobjectOptional
PII MTL: 30 days

A list of objects where each object represents the result of processing a correlation_id. Each object contains the following fields: correlation_id, a unique 32-character UUID that maps the response to the original request; error_code, an integer where 0 indicates success and any non-zero value represents an error; and error_messages, an array of strings describing specific validation errors encountered. If the request is successful, the error_messages array will be empty.


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

request-body-parameters page anchor
Encoding type:application/x-www-form-urlencoded
SchemaExample
Property nameTypeRequiredDescriptionChild properties
Itemsarrayrequired

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]; and 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].

Upsert Consents in BulkLink to code sample: Upsert Consents in Bulk
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
status: "opt-in",
18
source: "website",
19
},
20
{
21
contact_id: "+19",
22
correlation_id: "02520cfa6c432f0e3ec3a38c122d428d",
23
sender_id: "12345",
24
status: "opt-out",
25
source: "opt-out-message",
26
},
27
],
28
});
29
30
console.log(bulkConsent.items);
31
}
32
33
createBulkConsents();

Output

1
{
2
"items": [
3
{
4
"correlation_id": "ad388b5a46b33b874b0d41f7226db2ef",
5
"error_code": 0,
6
"error_messages": []
7
},
8
{
9
"correlation_id": "02520cfa6c432f0e3ec3a38c122d428d",
10
"error_code": 30646,
11
"error_messages": [
12
"INVALID_CONTACT_ID"
13
]
14
}
15
]
16
}

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.