# Contacts

## List

**get** `/api/v2/contacts`

Retrieve a list of contacts for the authenticated account

### Query Parameters

- `cid: optional string`

  Filter by contact ID

- `limit: optional number`

  Maximum number of contacts to return

- `offset: optional number`

  Number of contacts to skip

- `order_by: optional string`

  Field to sort by

- `order_direction: optional "asc" or "desc"`

  Sort direction

  - `"asc"`

  - `"desc"`

- `phone_number: optional string`

  Filter by phone number

### Returns

- `assigned_to_email: optional string`

  Email of assigned user

- `company_name: optional string`

  Company name

- `created_at: optional string`

  When the contact was created

- `custom_variables: optional map[string]`

  Custom key-value pairs stored on the contact. Keys are human-readable labels.

- `first_name: optional string`

  First name

- `last_name: optional string`

  Last name

- `phone: optional string`

  Phone number in E.164 format

- `sendblue_number: optional string`

  Associated Sendblue phone number

- `tags: optional array of string`

  Tags associated with the contact

- `verified: optional boolean`

  Whether the contact is verified

### Example

```http
curl https://api.sendblue.co/api/v2/contacts \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"
```

## Create

**post** `/api/v2/contacts`

Create a new contact or update existing if update_if_exists is true

### Body Parameters

- `number: string`

  Contact's phone number in E.164 format (preferred)

- `assigned_to_email: optional string`

  Email of assigned user (preferred)

- `assignedToEmail: optional string`

  Email of assigned user (deprecated, use assigned_to_email)

- `custom_variables: optional map[string]`

  Custom key-value pairs. Keys are human-readable labels; new labels are auto-created.

- `first_name: optional string`

  Contact's first name (preferred)

- `firstName: optional string`

  Contact's first name (deprecated, use first_name)

- `last_name: optional string`

  Contact's last name (preferred)

- `lastName: optional string`

  Contact's last name (deprecated, use last_name)

- `phone_number: optional string`

  Contact's phone number (deprecated, use number)

- `phoneNumber: optional string`

  Contact's phone number (deprecated, use number)

- `sendblue_number: optional string`

  Associated Sendblue phone number to send with (preferred)

- `sendblueNumber: optional string`

  Associated Sendblue phone number (deprecated, use sendblue_number)

- `tags: optional array of string`

  Tags for the contact

- `update_if_exists: optional boolean`

  If true, updates the contact if it already exists

### Returns

- `contact: optional Contact`

  - `assigned_to_email: optional string`

    Email of assigned user

  - `company_name: optional string`

    Company name

  - `created_at: optional string`

    When the contact was created

  - `custom_variables: optional map[string]`

    Custom key-value pairs stored on the contact. Keys are human-readable labels.

  - `first_name: optional string`

    First name

  - `last_name: optional string`

    Last name

  - `phone: optional string`

    Phone number in E.164 format

  - `sendblue_number: optional string`

    Associated Sendblue phone number

  - `tags: optional array of string`

    Tags associated with the contact

  - `verified: optional boolean`

    Whether the contact is verified

- `status: optional string`

### Example

```http
curl https://api.sendblue.co/api/v2/contacts \
    -H 'Content-Type: application/json' \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET" \
    -d '{
          "number": "number",
          "custom_variables": {
            "Lead Source": "Website"
          }
        }'
```

## Count

**get** `/api/v2/contacts/count`

Get the total number of contacts

### Returns

- `count: optional number`

  Total number of contacts

### Example

```http
curl https://api.sendblue.co/api/v2/contacts/count \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"
```

## Verify

**post** `/api/v2/contacts/verify`

Send a verification message to a contact

### Body Parameters

- `number: string`

  Phone number to verify

### Returns

- `status: optional string`

### Example

```http
curl https://api.sendblue.co/api/v2/contacts/verify \
    -H 'Content-Type: application/json' \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET" \
    -d '{
          "number": "number"
        }'
```

## Retrieve

**get** `/api/v2/contacts/{phone_number}`

Retrieve a specific contact by phone number

### Path Parameters

- `phone_number: string`

### Returns

- `contact: optional Contact`

  - `assigned_to_email: optional string`

    Email of assigned user

  - `company_name: optional string`

    Company name

  - `created_at: optional string`

    When the contact was created

  - `custom_variables: optional map[string]`

    Custom key-value pairs stored on the contact. Keys are human-readable labels.

  - `first_name: optional string`

    First name

  - `last_name: optional string`

    Last name

  - `phone: optional string`

    Phone number in E.164 format

  - `sendblue_number: optional string`

    Associated Sendblue phone number

  - `tags: optional array of string`

    Tags associated with the contact

  - `verified: optional boolean`

    Whether the contact is verified

- `status: optional string`

### Example

```http
curl https://api.sendblue.co/api/v2/contacts/$PHONE_NUMBER \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"
```

## Update

**put** `/api/v2/contacts/{phone_number}`

Update an existing contact

### Path Parameters

- `phone_number: string`

### Body Parameters

- `assigned_to_email: optional string`

  Email of assigned user (preferred)

- `assignedToEmail: optional string`

  Deprecated, use assigned_to_email

- `company_name: optional string`

  Company name (preferred)

- `companyName: optional string`

  Deprecated, use company_name

- `custom_variables: optional map[string]`

  Custom key-value pairs. Merged with existing variables (not replaced).

- `first_name: optional string`

  Contact's first name (preferred)

- `firstName: optional string`

  Deprecated, use first_name

- `last_name: optional string`

  Contact's last name (preferred)

- `lastName: optional string`

  Deprecated, use last_name

- `sendblue_number: optional string`

  Associated Sendblue phone number (preferred)

- `sendblueNumber: optional string`

  Deprecated, use sendblue_number

- `tags: optional array of string`

### Returns

- `contact: optional Contact`

  - `assigned_to_email: optional string`

    Email of assigned user

  - `company_name: optional string`

    Company name

  - `created_at: optional string`

    When the contact was created

  - `custom_variables: optional map[string]`

    Custom key-value pairs stored on the contact. Keys are human-readable labels.

  - `first_name: optional string`

    First name

  - `last_name: optional string`

    Last name

  - `phone: optional string`

    Phone number in E.164 format

  - `sendblue_number: optional string`

    Associated Sendblue phone number

  - `tags: optional array of string`

    Tags associated with the contact

  - `verified: optional boolean`

    Whether the contact is verified

- `status: optional string`

### Example

```http
curl https://api.sendblue.co/api/v2/contacts/$PHONE_NUMBER \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET" \
    -d '{
          "custom_variables": {
            "Plan": "Premium"
          }
        }'
```

## Delete

**delete** `/api/v2/contacts/{phone_number}`

Delete a specific contact

### Path Parameters

- `phone_number: string`

### Returns

- `status: optional string`

### Example

```http
curl https://api.sendblue.co/api/v2/contacts/$PHONE_NUMBER \
    -X DELETE \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"
```

## Domain Types

### Contact

- `Contact = object { assigned_to_email, company_name, created_at, 7 more }`

  - `assigned_to_email: optional string`

    Email of assigned user

  - `company_name: optional string`

    Company name

  - `created_at: optional string`

    When the contact was created

  - `custom_variables: optional map[string]`

    Custom key-value pairs stored on the contact. Keys are human-readable labels.

  - `first_name: optional string`

    First name

  - `last_name: optional string`

    Last name

  - `phone: optional string`

    Phone number in E.164 format

  - `sendblue_number: optional string`

    Associated Sendblue phone number

  - `tags: optional array of string`

    Tags associated with the contact

  - `verified: optional boolean`

    Whether the contact is verified

# Bulk

## Delete

**delete** `/api/v2/contacts`

Delete multiple contacts by their IDs

### Body Parameters

- `contact_ids: array of string`

  Array of phone numbers in E.164 format to delete

### Returns

- `amount: optional number`

  Number of contacts deleted

- `status: optional string`

### Example

```http
curl https://api.sendblue.co/api/v2/contacts \
    -X DELETE \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET"
```

## Create

**post** `/api/v2/contacts/bulk`

Create multiple contacts in bulk

### Body Parameters

- `contacts: array of object { phone, company_name, custom_variables, 3 more }`

  - `phone: string`

    Phone number in E.164 format

  - `company_name: optional string`

    Company name

  - `custom_variables: optional map[string]`

    Custom key-value pairs. Keys are human-readable labels; new labels are auto-created.

  - `first_name: optional string`

    Contact's first name

  - `last_name: optional string`

    Contact's last name

  - `tags: optional array of string`

### Returns

- `contacts: optional array of Contact`

  - `assigned_to_email: optional string`

    Email of assigned user

  - `company_name: optional string`

    Company name

  - `created_at: optional string`

    When the contact was created

  - `custom_variables: optional map[string]`

    Custom key-value pairs stored on the contact. Keys are human-readable labels.

  - `first_name: optional string`

    First name

  - `last_name: optional string`

    Last name

  - `phone: optional string`

    Phone number in E.164 format

  - `sendblue_number: optional string`

    Associated Sendblue phone number

  - `tags: optional array of string`

    Tags associated with the contact

  - `verified: optional boolean`

    Whether the contact is verified

- `status: optional string`

### Example

```http
curl https://api.sendblue.co/api/v2/contacts/bulk \
    -H 'Content-Type: application/json' \
    -H "sb-api-key-id: $SENDBLUE_API_API_KEY" \
    -H "sb-api-secret-key: $SENDBLUE_API_API_SECRET" \
    -d '{
          "contacts": [
            {
              "phone": "phone"
            }
          ]
        }'
```