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!
Note : Bulk Upsert Contacts API currently only supports the SMS channel.
Not a HIPAA Eligible Service: Bulk Upsert Contacts is not a HIPAA Eligible Service and should not be used in Bulk Upsert Contacts workflows that are subject to HIPAA.
The Bulk Upsert Contacts API allows you to create or update (upsert) contact information for your users at once. You can provide details such as contact_id, correlation_id, country_iso_code, and zip_code.
Bulk Upsert Contacts API provides a built-in rate limit of 100 requests per minute. If you reach this limit, you will start receiving HTTP 429 "Too Many Requests" responses.
Bulk Upsert Contacts API has a timeout value of 3 seconds. However, its 99th percentile is within 1 second.
These properties are returned in the JSON response output.
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/Contacts/BulkCreates up to 25 contacts for an authenticated account. If a contact already exists, it will be upserted—updated to match the requested object.
Every contact 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 contact object, the error will be returned and mapped specifically to that contact'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 30647, which provides guidance on common errors such as incorrect phone number format, missing required fields, and other validation issues.
application/x-www-form-urlencodedA list of objects where each object represents a contact's details. Each object includes the following fields: contact_id, which must be a string representing phone number in E.164 format; correlation_id, a unique 32-character UUID that maps the response to the original request; country_iso_code, a string representing the country using the ISO format (e.g., US for the United States); and zip_code, a string representing the postal code.
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 createBulkContacts() {11const bulkContact = await client.accounts.v1.bulkContacts.create({12items: [13{14contact_id: "+19999999999",15correlation_id: "ad388b5a46b33b874b0d41f7226db2eh",16country_iso_code: "US",17zip_code: "12345",18},19{20contact_id: "+19",21correlation_id: "02520cfa6c432f0e3ec3a38c122d428a",22country_iso_code: "US",23zip_code: "12345",24},25],26});2728console.log(bulkContact.items);29}3031createBulkContacts();
1{2"items": [3{4"correlation_id": "ad388b5a46b33b874b0d41f7226db2eh",5"error_code": 0,6"error_messages": []7},8{9"correlation_id": "02520cfa6c432f0e3ec3a38c122d428a",10"error_code": 30647,11"error_messages": [12"INVALID_CONTACT_ID"13]14}15]16}