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.
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.
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.
These properties are returned in the JSON response.
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/BulkCreates 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.
application/x-www-form-urlencodedThis 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].
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createBulkConsents() {11const bulkConsent = await client.accounts.v1.bulkConsents.create({12items: [13{14contact_id: "+19999999991",15correlation_id: "ad388b5a46b33b874b0d41f7226db2ef",16sender_id: "MG00000000000000000000000000000000",17status: "opt-in",18source: "website",19},20{21contact_id: "+19",22correlation_id: "02520cfa6c432f0e3ec3a38c122d428d",23sender_id: "12345",24status: "opt-out",25source: "opt-out-message",26},27],28});2930console.log(bulkConsent.items);31}3233createBulkConsents();
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}