API v2

Contacts API

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

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": "[email protected]",
    "tags": ["VIP", "Customer"],
    "sendblueNumber": "+19175559876",
    "created_at": "2024-01-15T10:30:00Z",
    "assignedToEmail": "[email protected]",
    "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

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": "[email protected]",
    "tags": ["VIP"],
    "sendblueNumber": "+19175559876",
    "created_at": "2024-01-15T10:30:00Z",
    "assignedToEmail": "[email protected]",
    "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

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

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": "[email protected]",
    "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

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

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": "[email protected]",
    "tags": ["VIP", "Enterprise"],
    "sendblueNumber": "+19175559876",
    "assignedToEmail": "[email protected]",
    "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

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

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

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).
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.
Input Field Names: Both snake_case (custom_variables, first_name) and camelCase (customVariables, firstName) are accepted on input. Responses use camelCase.
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).
Authentication: All endpoints require sb-api-key-id and sb-api-secret-key headers.
Rate Limits: Contacts endpoints are rate-limited to 100 requests per 10 seconds.