# Contact API > \[!NOTE] > > Contacts API only supports **SMS**. > > Customers using Twilio's [Compliance Toolkit](/docs/messaging/features/compliance-toolkit) obtain default access at this time. > > This Pilot is available for early adopter customers to test and provide feedback. > \[!WARNING] > > Contacts API is currently available as a limited Pilot release 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. As a Pilot release, Consent Management API is made available to a limited number of Customers for testing purposes. Pilot products are not covered by the Twilio Support Terms or the [Twilio Service Level Agreement](https://www.twilio.com/en-us/legal/service-level-agreement/twilio-apis). > > Contact API is not a HIPAA Eligible Service and should not be used in workflows that are subject to HIPAA. The Twilio Contact API helps manage and synchronize user profile information. If you use [Compliance Toolkit](/docs/messaging/features/compliance-toolkit), the Contact API enables you to provide the known ZIP code of your end users for more accurate quiet hours enforcement. * By default, Compliance Toolkit infers the time zone from the phone number's area code. * When available, Compliance Toolkit prefers the stored `zip_code` value to determine a user's local time. ## Rate limits 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. ## Timeouts Contact API has a timeout value of 3 seconds. However, its 99th percentile is within 1 second. ## Contact API Response Properties These properties are returned in the JSON response output. ```json {"type":"object","refName":"accounts.v1.bulk_contacts","modelName":"accounts_v1_bulk_contacts","properties":{"items":{"nullable":true,"description":"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.","x-twilio":{"pii":{"handling":"standard","deleteSla":30}}}}} ``` ## Upsert Contacts in Bulk `POST https://accounts.twilio.com/v1/Contacts/Bulk` Creates 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](/docs/api/errors/30647), which provides guidance on common errors such as incorrect phone number format, missing required fields, and other validation issues. ### Request body parameters ```json {"schema":{"type":"object","title":"CreateBulkContactsRequest","required":["Items"],"properties":{"Items":{"type":"array","description":"A 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](/docs/glossary/what-e164); `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.","x-twilio":{"pii":{"handling":"standard","deleteSla":30}}}}},"examples":{"post":{"value":{"lang":"json","value":"{\n \"Items\": [\n \"{\\\"contact_id\\\":\\\"+19999999999\\\",\\\"correlation_id\\\":\\\"ad388b5a46b33b874b0d41f7226db2eh\\\",\\\"country_iso_code\\\":\\\"US\\\",\\\"zip_code\\\":\\\"12345\\\"}\",\n \"{\\\"contact_id\\\":\\\"+19\\\",\\\"correlation_id\\\":\\\"02520cfa6c432f0e3ec3a38c122d428a\\\",\\\"country_iso_code\\\":\\\"US\\\",\\\"zip_code\\\":\\\"12345\\\"}\"\n ]\n}","meta":"","code":"{\n \"Items\": [\n \"{\\\"contact_id\\\":\\\"+19999999999\\\",\\\"correlation_id\\\":\\\"ad388b5a46b33b874b0d41f7226db2eh\\\",\\\"country_iso_code\\\":\\\"US\\\",\\\"zip_code\\\":\\\"12345\\\"}\",\n \"{\\\"contact_id\\\":\\\"+19\\\",\\\"correlation_id\\\":\\\"02520cfa6c432f0e3ec3a38c122d428a\\\",\\\"country_iso_code\\\":\\\"US\\\",\\\"zip_code\\\":\\\"12345\\\"}\"\n ]\n}","tokens":[["{","#C9D1D9"],"\n ",["\"Items\"","#7EE787"],[": [","#C9D1D9"],"\n ",["\"{","#A5D6FF"],["\\\"","#79C0FF"],["contact_id","#A5D6FF"],["\\\"","#79C0FF"],[":","#A5D6FF"],["\\\"","#79C0FF"],["+19999999999","#A5D6FF"],["\\\"","#79C0FF"],[",","#A5D6FF"],["\\\"","#79C0FF"],["correlation_id","#A5D6FF"],["\\\"","#79C0FF"],[":","#A5D6FF"],["\\\"","#79C0FF"],["ad388b5a46b33b874b0d41f7226db2eh","#A5D6FF"],["\\\"","#79C0FF"],[",","#A5D6FF"],["\\\"","#79C0FF"],["country_iso_code","#A5D6FF"],["\\\"","#79C0FF"],[":","#A5D6FF"],["\\\"","#79C0FF"],["US","#A5D6FF"],["\\\"","#79C0FF"],[",","#A5D6FF"],["\\\"","#79C0FF"],["zip_code","#A5D6FF"],["\\\"","#79C0FF"],[":","#A5D6FF"],["\\\"","#79C0FF"],["12345","#A5D6FF"],["\\\"","#79C0FF"],["}\"","#A5D6FF"],[",","#C9D1D9"],"\n ",["\"{","#A5D6FF"],["\\\"","#79C0FF"],["contact_id","#A5D6FF"],["\\\"","#79C0FF"],[":","#A5D6FF"],["\\\"","#79C0FF"],["+19","#A5D6FF"],["\\\"","#79C0FF"],[",","#A5D6FF"],["\\\"","#79C0FF"],["correlation_id","#A5D6FF"],["\\\"","#79C0FF"],[":","#A5D6FF"],["\\\"","#79C0FF"],["02520cfa6c432f0e3ec3a38c122d428a","#A5D6FF"],["\\\"","#79C0FF"],[",","#A5D6FF"],["\\\"","#79C0FF"],["country_iso_code","#A5D6FF"],["\\\"","#79C0FF"],[":","#A5D6FF"],["\\\"","#79C0FF"],["US","#A5D6FF"],["\\\"","#79C0FF"],[",","#A5D6FF"],["\\\"","#79C0FF"],["zip_code","#A5D6FF"],["\\\"","#79C0FF"],[":","#A5D6FF"],["\\\"","#79C0FF"],["12345","#A5D6FF"],["\\\"","#79C0FF"],["}\"","#A5D6FF"],"\n ",["]","#C9D1D9"],"\n",["}","#C9D1D9"]],"annotations":[],"themeName":"github-dark","style":{"color":"#c9d1d9","background":"#0d1117"}}}},"encodingType":"application/x-www-form-urlencoded","conditionalParameterMap":{}} ``` Upsert Contacts in Bulk ```js // Download the helper library from https://www.twilio.com/docs/node/install const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio"; // Find your Account SID and Auth Token at twilio.com/console // and set the environment variables. See http://twil.io/secure const accountSid = process.env.TWILIO_ACCOUNT_SID; const authToken = process.env.TWILIO_AUTH_TOKEN; const client = twilio(accountSid, authToken); async function createBulkContacts() { const bulkContact = await client.accounts.v1.bulkContacts.create({ items: [ { contact_id: "+19999999999", correlation_id: "ad388b5a46b33b874b0d41f7226db2eh", country_iso_code: "US", zip_code: "12345", }, { contact_id: "+19", correlation_id: "02520cfa6c432f0e3ec3a38c122d428a", country_iso_code: "US", zip_code: "12345", }, ], }); console.log(bulkContact.items); } createBulkContacts(); ``` ```python # Download the helper library from https://www.twilio.com/docs/python/install import os from twilio.rest import Client # Find your Account SID and Auth Token at twilio.com/console # and set the environment variables. See http://twil.io/secure account_sid = os.environ["TWILIO_ACCOUNT_SID"] auth_token = os.environ["TWILIO_AUTH_TOKEN"] client = Client(account_sid, auth_token) bulk_contact = client.accounts.v1.bulk_contacts.create( items=[ { "contact_id": "+19999999999", "correlation_id": "ad388b5a46b33b874b0d41f7226db2eh", "country_iso_code": "US", "zip_code": "12345", }, { "contact_id": "+19", "correlation_id": "02520cfa6c432f0e3ec3a38c122d428a", "country_iso_code": "US", "zip_code": "12345", }, ] ) print(bulk_contact.items) ``` ```csharp // Install the C# / .NET helper library from twilio.com/docs/csharp/install using System; using Twilio; using Twilio.Rest.Accounts.V1; using System.Threading.Tasks; using System.Collections.Generic; class Program { public static async Task Main(string[] args) { // Find your Account SID and Auth Token at twilio.com/console // and set the environment variables. See http://twil.io/secure string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID"); string authToken = Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN"); TwilioClient.Init(accountSid, authToken); var bulkContacts = await BulkContactsResource.CreateAsync( items: new List { new Dictionary() { { "contact_id", "+19999999999" }, { "correlation_id", "ad388b5a46b33b874b0d41f7226db2eh" }, { "country_iso_code", "US" }, { "zip_code", "12345" } }, new Dictionary() { { "contact_id", "+19" }, { "correlation_id", "02520cfa6c432f0e3ec3a38c122d428a" }, { "country_iso_code", "US" }, { "zip_code", "12345" } } }); Console.WriteLine(bulkContacts.Items); } } ``` ```java // Install the Java helper library from twilio.com/docs/java/install import java.util.Arrays; import java.util.HashMap; import com.twilio.Twilio; import com.twilio.rest.accounts.v1.BulkContacts; public class Example { // Find your Account SID and Auth Token at twilio.com/console // and set the environment variables. See http://twil.io/secure public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID"); public static final String AUTH_TOKEN = System.getenv("TWILIO_AUTH_TOKEN"); public static void main(String[] args) { Twilio.init(ACCOUNT_SID, AUTH_TOKEN); BulkContacts bulkContacts = BulkContacts .creator(Arrays.asList( new HashMap() { { put("contact_id", "+19999999999"); put("correlation_id", "ad388b5a46b33b874b0d41f7226db2eh"); put("country_iso_code", "US"); put("zip_code", "12345"); } }, new HashMap() { { put("contact_id", "+19"); put("correlation_id", "02520cfa6c432f0e3ec3a38c122d428a"); put("country_iso_code", "US"); put("zip_code", "12345"); } })) .create(); System.out.println(bulkContacts.getItems()); } } ``` ```go // Download the helper library from https://www.twilio.com/docs/go/install package main import ( "fmt" "github.com/twilio/twilio-go" accounts "github.com/twilio/twilio-go/rest/accounts/v1" "os" ) func main() { // Find your Account SID and Auth Token at twilio.com/console // and set the environment variables. See http://twil.io/secure // Make sure TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN exists in your environment client := twilio.NewRestClient() params := &accounts.CreateBulkContactsParams{} params.SetItems([]interface{}{ map[string]interface{}{ "contact_id": "+19999999999", "correlation_id": "ad388b5a46b33b874b0d41f7226db2eh", "country_iso_code": "US", "zip_code": "12345", }, map[string]interface{}{ "contact_id": "+19", "correlation_id": "02520cfa6c432f0e3ec3a38c122d428a", "country_iso_code": "US", "zip_code": "12345", }, }) resp, err := client.AccountsV1.CreateBulkContacts(params) if err != nil { fmt.Println(err.Error()) os.Exit(1) } else { if resp.Items != nil { fmt.Println(*resp.Items) } else { fmt.Println(resp.Items) } } } ``` ```php accounts->v1->bulkContacts->create( [ [ "contact_id" => "+19999999999", "correlation_id" => "ad388b5a46b33b874b0d41f7226db2eh", "country_iso_code" => "US", "zip_code" => "12345", ], [ "contact_id" => "+19", "correlation_id" => "02520cfa6c432f0e3ec3a38c122d428a", "country_iso_code" => "US", "zip_code" => "12345", ], ] // Items ); print $bulk_contact->items; ``` ```ruby # Download the helper library from https://www.twilio.com/docs/ruby/install require 'twilio-ruby' # Find your Account SID and Auth Token at twilio.com/console # and set the environment variables. See http://twil.io/secure account_sid = ENV['TWILIO_ACCOUNT_SID'] auth_token = ENV['TWILIO_AUTH_TOKEN'] @client = Twilio::REST::Client.new(account_sid, auth_token) bulk_contact = @client .accounts .v1 .bulk_contacts .create( items: [ { 'contact_id' => '+19999999999', 'correlation_id' => 'ad388b5a46b33b874b0d41f7226db2eh', 'country_iso_code' => 'US', 'zip_code' => '12345' }, { 'contact_id' => '+19', 'correlation_id' => '02520cfa6c432f0e3ec3a38c122d428a', 'country_iso_code' => 'US', 'zip_code' => '12345' } ] ) puts bulk_contact.items ``` ```bash # Install the twilio-cli from https://twil.io/cli twilio api:accounts:v1:contacts:bulk:create \ --items "{\"contact_id\":\"+19999999999\",\"correlation_id\":\"ad388b5a46b33b874b0d41f7226db2eh\",\"country_iso_code\":\"US\",\"zip_code\":\"12345\"}" "{\"contact_id\":\"+19\",\"correlation_id\":\"02520cfa6c432f0e3ec3a38c122d428a\",\"country_iso_code\":\"US\",\"zip_code\":\"12345\"}" ``` ```bash curl -X POST "https://accounts.twilio.com/v1/Contacts/Bulk" \ --data-urlencode "Items={\"contact_id\":\"+19999999999\",\"correlation_id\":\"ad388b5a46b33b874b0d41f7226db2eh\",\"country_iso_code\":\"US\",\"zip_code\":\"12345\"}" \ --data-urlencode "Items={\"contact_id\":\"+19\",\"correlation_id\":\"02520cfa6c432f0e3ec3a38c122d428a\",\"country_iso_code\":\"US\",\"zip_code\":\"12345\"}" \ -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN ``` ```json { "items": [ { "contact_id": "+19999999999", "correlation_id": "ad388b5a46b33b874b0d41f7226db2eh", "country_iso_code": "US", "zip_code": "12345" }, { "contact_id": "+19", "correlation_id": "02520cfa6c432f0e3ec3a38c122d428a", "country_iso_code": "US", "zip_code": "12345" } ] } ```