--- title: Contacts API | Sendblue Docs description: Create, read, update, and delete contacts via the Sendblue API, including custom variable support --- Manage your contacts programmatically. The Contacts API supports full CRUD operations, tagging, assignment, and custom variables with human-readable labels. ## List Contacts Retrieve a paginated list of contacts for your account. ``` GET https://api.sendblue.co/api/v2/contacts ``` ### Query Parameters | Parameter | Type | Required | Description | | ----------------- | ------- | -------- | -------------------------------------------------------------------- | | `limit` | integer | No | Maximum number of contacts to return | | `offset` | integer | No | Number of contacts to skip (default: 0) | | `order_by` | string | No | Sort field: `created_at` (default), `firstName`, `lastName`, `phone` | | `order_direction` | string | No | `asc` or `desc` (default: `desc`) | | `phone_number` | string | No | Filter by phone number (E.164 format) | ### Example Request Terminal window ``` curl -X GET 'https://api.sendblue.co/api/v2/contacts?limit=10&offset=0&order_by=created_at&order_direction=desc' \ -H 'sb-api-key-id: YOUR_API_KEY' \ -H 'sb-api-secret-key: YOUR_API_SECRET' ``` ### Success Response (200) ``` [ { "firstName": "John", "lastName": "Doe", "phone": "+14155551234", "companyName": "user@example.com", "tags": ["VIP", "Customer"], "sendblueNumber": "+19175559876", "created_at": "2024-01-15T10:30:00Z", "assignedToEmail": "agent@example.com", "customVariables": { "Lead Source": "Website", "Plan": "Enterprise" } } ] ``` --- ## Get Single Contact Retrieve a single contact by phone number. ``` GET https://api.sendblue.co/api/v2/contacts/:phone_number ``` ### Path Parameters | Parameter | Type | Description | | -------------- | ------ | ------------------------------------------------------ | | `phone_number` | string | Phone number in E.164 format (URL-encode `+` as `%2B`) | ### Example Request Terminal window ``` curl -X GET 'https://api.sendblue.co/api/v2/contacts/%2B14155551234' \ -H 'sb-api-key-id: YOUR_API_KEY' \ -H 'sb-api-secret-key: YOUR_API_SECRET' ``` ### Success Response (200) ``` { "status": "OK", "contact": { "firstName": "John", "lastName": "Doe", "phone": "+14155551234", "companyName": "user@example.com", "tags": ["VIP"], "sendblueNumber": "+19175559876", "created_at": "2024-01-15T10:30:00Z", "assignedToEmail": "agent@example.com", "customVariables": { "Lead Source": "Website" } } } ``` --- ## Get Contact Count Get the total number of contacts for your account. ``` GET https://api.sendblue.co/api/v2/contacts/count ``` ### Query Parameters | Parameter | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------------------- | | `phone_number` | string | No | Filter count by phone number (E.164 format) | ### Example Request Terminal window ``` curl -X GET 'https://api.sendblue.co/api/v2/contacts/count' \ -H 'sb-api-key-id: YOUR_API_KEY' \ -H 'sb-api-secret-key: YOUR_API_SECRET' ``` ### Success Response (200) ``` { "count": 142 } ``` --- ## Create Contact Create a new contact. ``` POST https://api.sendblue.co/api/v2/contacts ``` ### Request Body | Parameter | Type | Required | Description | | ------------------- | --------- | -------- | ---------------------------------------------------------------------------------------- | | `number` | string | Yes | Phone number in E.164 format | | `first_name` | string | No | First name | | `last_name` | string | No | Last name | | `sendblue_number` | string | No | Associated Sendblue phone number | | `tags` | string\[] | No | Array of tag labels | | `assigned_to_email` | string | No | Email of user to assign this contact to | | `update_if_exists` | boolean | No | If `true`, updates the contact if it already exists (default: `false`) | | `custom_variables` | object | No | Custom key-value pairs. Keys are human-readable labels; unknown labels are auto-created. | ### Example Request Terminal window ``` curl -X POST 'https://api.sendblue.co/api/v2/contacts' \ -H 'sb-api-key-id: YOUR_API_KEY' \ -H 'sb-api-secret-key: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{ "number": "+14155551234", "first_name": "John", "last_name": "Doe", "tags": ["VIP", "Customer"], "custom_variables": { "Lead Source": "Website", "Plan": "Enterprise" } }' ``` ### Success Response (200) ``` { "status": "OK", "contact": { "firstName": "John", "lastName": "Doe", "phone": "+14155551234", "companyName": "user@example.com", "tags": ["VIP", "Customer"], "customVariables": { "Lead Source": "Website", "Plan": "Enterprise" } } } ``` --- ## Bulk Create Create multiple contacts in a single request. ``` POST https://api.sendblue.co/api/v2/contacts/bulk ``` ### Request Body | Parameter | Type | Required | Description | | ---------- | ----- | -------- | ------------------------ | | `contacts` | array | Yes | Array of contact objects | Each contact object: | Field | Type | Required | Description | | ----------------- | --------- | -------- | ---------------------------------------------------------------------------------------- | | `phone` | string | Yes | Phone number in E.164 format | | `firstName` | string | No | First name | | `lastName` | string | No | Last name | | `company` | string | No | Company name | | `tags` | string\[] | No | Array of tag labels | | `customVariables` | object | No | Custom key-value pairs. Keys are human-readable labels; unknown labels are auto-created. | ### Example Request Terminal window ``` curl -X POST 'https://api.sendblue.co/api/v2/contacts/bulk' \ -H 'sb-api-key-id: YOUR_API_KEY' \ -H 'sb-api-secret-key: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{ "contacts": [ { "firstName": "John", "lastName": "Doe", "phone": "+14155551234", "tags": ["VIP"], "customVariables": { "Lead Source": "Website" } }, { "firstName": "Jane", "lastName": "Smith", "phone": "+14155555678", "tags": ["Customer"], "customVariables": { "Lead Source": "Referral" } } ] }' ``` ### Success Response (200) ``` { "status": "OK", "contacts": [ { "firstName": "John", "lastName": "Doe", "phone": "+14155551234", "tags": ["VIP"], "customVariables": { "Lead Source": "Website" } } ], "numberOfContactsCreated": 2, "failures": [ { "contact": { "phone": "+invalid" }, "error": "Invalid phone number" } ] } ``` > The `failures` array is only included if some contacts failed to create. --- ## Update Contact Update an existing contact by phone number. ``` PUT https://api.sendblue.co/api/v2/contacts/:phone_number ``` ### Path Parameters | Parameter | Type | Description | | -------------- | ------ | ------------------------------------------------------ | | `phone_number` | string | Phone number in E.164 format (URL-encode `+` as `%2B`) | ### Request Body | Parameter | Type | Required | Description | | ------------------- | --------- | -------- | -------------------------------------------------------------------------------- | | `first_name` | string | No | First name | | `last_name` | string | No | Last name | | `sendblue_number` | string | No | Associated Sendblue phone number | | `assigned_to_email` | string | No | Email of user to assign this contact to | | `tags` | string\[] | No | Array of tag labels. **Replaces** all existing tags — pass the full desired set. | | `custom_variables` | object | No | Custom key-value pairs. **Merged** with existing variables (not replaced). | | `phone_number` | string | No | New phone number (if updating the phone number itself) | > **Important:** `tags` are **replaced** entirely on update, while `custom_variables` are **merged** with existing values. ### Example Request Terminal window ``` curl -X PUT 'https://api.sendblue.co/api/v2/contacts/%2B14155551234' \ -H 'sb-api-key-id: YOUR_API_KEY' \ -H 'sb-api-secret-key: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{ "first_name": "John", "tags": ["VIP", "Enterprise"], "custom_variables": { "Plan": "Premium" } }' ``` ### Success Response (200) ``` { "status": "OK", "contact": { "firstName": "John", "lastName": "Doe", "phone": "+14155551234", "companyName": "user@example.com", "tags": ["VIP", "Enterprise"], "sendblueNumber": "+19175559876", "assignedToEmail": "agent@example.com", "created_at": "2024-01-15T10:30:00Z", "customVariables": { "Lead Source": "Website", "Plan": "Premium" } } } ``` --- ## Delete Contact Delete a single contact by phone number. ``` DELETE https://api.sendblue.co/api/v2/contacts/:phone_number ``` ### Path Parameters | Parameter | Type | Description | | -------------- | ------ | ------------------------------------------------------ | | `phone_number` | string | Phone number in E.164 format (URL-encode `+` as `%2B`) | ### Example Request Terminal window ``` curl -X DELETE 'https://api.sendblue.co/api/v2/contacts/%2B14155551234' \ -H 'sb-api-key-id: YOUR_API_KEY' \ -H 'sb-api-secret-key: YOUR_API_SECRET' ``` ### Success Response (200) ``` { "status": "OK" } ``` --- ## Bulk Delete Delete multiple contacts by phone number. ``` DELETE https://api.sendblue.co/api/v2/contacts ``` ### Request Body | Parameter | Type | Required | Description | | ------------- | --------- | -------- | -------------------------------------- | | `contact_ids` | string\[] | Yes | Array of phone numbers in E.164 format | ### Example Request Terminal window ``` curl -X DELETE 'https://api.sendblue.co/api/v2/contacts' \ -H 'sb-api-key-id: YOUR_API_KEY' \ -H 'sb-api-secret-key: YOUR_API_SECRET' \ -H 'Content-Type: application/json' \ -d '{ "contact_ids": ["+14155551234", "+14155555678"] }' ``` ### Success Response (200) ``` { "status": "OK", "amount": 2, "total": 2, "successes": 2, "failures": 0 } ``` --- ## Error Responses ### Missing or Invalid Fields (400) ``` { "status": "ERROR", "message": "Missing fields" } ``` ### Unauthorized (401) ``` { "status": "ERROR", "message": "Unauthorized" } ``` ### Contact Not Found (404) ``` { "status": "ERROR", "message": "Contact not found" } ``` ### Contact Already Exists (409) ``` { "status": "ERROR", "message": "Contact already exists" } ``` ### Rate Limit Exceeded (429) The Contacts API is rate-limited to **100 requests per 10 seconds** per account. --- ## Notes 1. **Phone Number Format**: All phone numbers must be in E.164 format (e.g., `+14155551234`). When passing phone numbers in URL paths, URL-encode the `+` as `%2B` (e.g., `%2B14155551234`). 2. **Custom Variables**: Keys are human-readable labels, not internal IDs. If you pass a label that doesn’t exist yet, it will be **automatically created** as a new custom variable definition on your account. 3. **Input Field Names**: Both `snake_case` (`custom_variables`, `first_name`) and `camelCase` (`customVariables`, `firstName`) are accepted on input. Responses use `camelCase`. 4. **Tags vs. Custom Variables on Update**: When updating a contact, `tags` are **replaced** entirely (pass the full desired set), while `custom_variables` are **merged** with existing values (only the keys you pass are updated). 5. **Authentication**: All endpoints require `sb-api-key-id` and `sb-api-secret-key` headers. 6. **Rate Limits**: Contacts endpoints are rate-limited to 100 requests per 10 seconds.