# Contacts

## List

`contacts.list(ContactListParams**kwargs)  -> ContactListResponse`

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

Retrieve a list of contacts for the authenticated account

### Parameters

- `cid: Optional[str]`

  Filter by contact ID

- `limit: Optional[int]`

  Maximum number of contacts to return

- `offset: Optional[int]`

  Number of contacts to skip

- `order_by: Optional[str]`

  Field to sort by

- `order_direction: Optional[Literal["asc", "desc"]]`

  Sort direction

  - `"asc"`

  - `"desc"`

- `phone_number: Optional[str]`

  Filter by phone number

### Returns

- `List[Contact]`

  - `assigned_to_email: Optional[str]`

    Email of assigned user

  - `company_name: Optional[str]`

    Company name

  - `created_at: Optional[datetime]`

    When the contact was created

  - `custom_variables: Optional[Dict[str, str]]`

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

  - `first_name: Optional[str]`

    First name

  - `last_name: Optional[str]`

    Last name

  - `phone: Optional[str]`

    Phone number in E.164 format

  - `sendblue_number: Optional[str]`

    Associated Sendblue phone number

  - `tags: Optional[List[str]]`

    Tags associated with the contact

  - `verified: Optional[bool]`

    Whether the contact is verified

### Example

```python
import os
from sendblue_api import SendblueAPI

client = SendblueAPI(
    api_key=os.environ.get("SENDBLUE_API_API_KEY"),  # This is the default and can be omitted
    api_secret=os.environ.get("SENDBLUE_API_API_SECRET"),  # This is the default and can be omitted
)
contacts = client.contacts.list()
print(contacts)
```

## Create

`contacts.create(ContactCreateParams**kwargs)  -> ContactCreateResponse`

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

Create a new contact or update existing if update_if_exists is true

### Parameters

- `number: str`

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

- `assigned_to_email: Optional[str]`

  Email of assigned user (preferred)

- `assigned_to_email: Optional[str]`

  Email of assigned user (deprecated, use assigned_to_email)

- `custom_variables: Optional[Dict[str, str]]`

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

- `first_name: Optional[str]`

  Contact's first name (preferred)

- `first_name: Optional[str]`

  Contact's first name (deprecated, use first_name)

- `last_name: Optional[str]`

  Contact's last name (preferred)

- `last_name: Optional[str]`

  Contact's last name (deprecated, use last_name)

- `phone_number: Optional[str]`

  Contact's phone number (deprecated, use number)

- `phone_number: Optional[str]`

  Contact's phone number (deprecated, use number)

- `sendblue_number: Optional[str]`

  Associated Sendblue phone number to send with (preferred)

- `sendblue_number: Optional[str]`

  Associated Sendblue phone number (deprecated, use sendblue_number)

- `tags: Optional[SequenceNotStr[str]]`

  Tags for the contact

- `update_if_exists: Optional[bool]`

  If true, updates the contact if it already exists

### Returns

- `class ContactCreateResponse: …`

  - `contact: Optional[Contact]`

    - `assigned_to_email: Optional[str]`

      Email of assigned user

    - `company_name: Optional[str]`

      Company name

    - `created_at: Optional[datetime]`

      When the contact was created

    - `custom_variables: Optional[Dict[str, str]]`

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

    - `first_name: Optional[str]`

      First name

    - `last_name: Optional[str]`

      Last name

    - `phone: Optional[str]`

      Phone number in E.164 format

    - `sendblue_number: Optional[str]`

      Associated Sendblue phone number

    - `tags: Optional[List[str]]`

      Tags associated with the contact

    - `verified: Optional[bool]`

      Whether the contact is verified

  - `status: Optional[str]`

### Example

```python
import os
from sendblue_api import SendblueAPI

client = SendblueAPI(
    api_key=os.environ.get("SENDBLUE_API_API_KEY"),  # This is the default and can be omitted
    api_secret=os.environ.get("SENDBLUE_API_API_SECRET"),  # This is the default and can be omitted
)
contact = client.contacts.create(
    number="number",
)
print(contact.contact)
```

## Count

`contacts.count()  -> ContactCountResponse`

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

Get the total number of contacts

### Returns

- `class ContactCountResponse: …`

  - `count: Optional[int]`

    Total number of contacts

### Example

```python
import os
from sendblue_api import SendblueAPI

client = SendblueAPI(
    api_key=os.environ.get("SENDBLUE_API_API_KEY"),  # This is the default and can be omitted
    api_secret=os.environ.get("SENDBLUE_API_API_SECRET"),  # This is the default and can be omitted
)
response = client.contacts.count()
print(response.count)
```

## Verify

`contacts.verify(ContactVerifyParams**kwargs)  -> ContactVerifyResponse`

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

Send a verification message to a contact

### Parameters

- `number: str`

  Phone number to verify

### Returns

- `class ContactVerifyResponse: …`

  - `status: Optional[str]`

### Example

```python
import os
from sendblue_api import SendblueAPI

client = SendblueAPI(
    api_key=os.environ.get("SENDBLUE_API_API_KEY"),  # This is the default and can be omitted
    api_secret=os.environ.get("SENDBLUE_API_API_SECRET"),  # This is the default and can be omitted
)
response = client.contacts.verify(
    number="number",
)
print(response.status)
```

## Retrieve

`contacts.retrieve(strphone_number)  -> ContactRetrieveResponse`

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

Retrieve a specific contact by phone number

### Parameters

- `phone_number: str`

### Returns

- `class ContactRetrieveResponse: …`

  - `contact: Optional[Contact]`

    - `assigned_to_email: Optional[str]`

      Email of assigned user

    - `company_name: Optional[str]`

      Company name

    - `created_at: Optional[datetime]`

      When the contact was created

    - `custom_variables: Optional[Dict[str, str]]`

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

    - `first_name: Optional[str]`

      First name

    - `last_name: Optional[str]`

      Last name

    - `phone: Optional[str]`

      Phone number in E.164 format

    - `sendblue_number: Optional[str]`

      Associated Sendblue phone number

    - `tags: Optional[List[str]]`

      Tags associated with the contact

    - `verified: Optional[bool]`

      Whether the contact is verified

  - `status: Optional[str]`

### Example

```python
import os
from sendblue_api import SendblueAPI

client = SendblueAPI(
    api_key=os.environ.get("SENDBLUE_API_API_KEY"),  # This is the default and can be omitted
    api_secret=os.environ.get("SENDBLUE_API_API_SECRET"),  # This is the default and can be omitted
)
contact = client.contacts.retrieve(
    "+1234567890",
)
print(contact.contact)
```

## Update

`contacts.update(strphone_number, ContactUpdateParams**kwargs)  -> ContactUpdateResponse`

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

Update an existing contact

### Parameters

- `phone_number: str`

- `assigned_to_email: Optional[str]`

  Email of assigned user (preferred)

- `assigned_to_email: Optional[str]`

  Deprecated, use assigned_to_email

- `company_name: Optional[str]`

  Company name (preferred)

- `company_name: Optional[str]`

  Deprecated, use company_name

- `custom_variables: Optional[Dict[str, str]]`

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

- `first_name: Optional[str]`

  Contact's first name (preferred)

- `first_name: Optional[str]`

  Deprecated, use first_name

- `last_name: Optional[str]`

  Contact's last name (preferred)

- `last_name: Optional[str]`

  Deprecated, use last_name

- `sendblue_number: Optional[str]`

  Associated Sendblue phone number (preferred)

- `sendblue_number: Optional[str]`

  Deprecated, use sendblue_number

- `tags: Optional[SequenceNotStr[str]]`

### Returns

- `class ContactUpdateResponse: …`

  - `contact: Optional[Contact]`

    - `assigned_to_email: Optional[str]`

      Email of assigned user

    - `company_name: Optional[str]`

      Company name

    - `created_at: Optional[datetime]`

      When the contact was created

    - `custom_variables: Optional[Dict[str, str]]`

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

    - `first_name: Optional[str]`

      First name

    - `last_name: Optional[str]`

      Last name

    - `phone: Optional[str]`

      Phone number in E.164 format

    - `sendblue_number: Optional[str]`

      Associated Sendblue phone number

    - `tags: Optional[List[str]]`

      Tags associated with the contact

    - `verified: Optional[bool]`

      Whether the contact is verified

  - `status: Optional[str]`

### Example

```python
import os
from sendblue_api import SendblueAPI

client = SendblueAPI(
    api_key=os.environ.get("SENDBLUE_API_API_KEY"),  # This is the default and can be omitted
    api_secret=os.environ.get("SENDBLUE_API_API_SECRET"),  # This is the default and can be omitted
)
contact = client.contacts.update(
    phone_number="+1234567890",
)
print(contact.contact)
```

## Delete

`contacts.delete(strphone_number)  -> ContactDeleteResponse`

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

Delete a specific contact

### Parameters

- `phone_number: str`

### Returns

- `class ContactDeleteResponse: …`

  - `status: Optional[str]`

### Example

```python
import os
from sendblue_api import SendblueAPI

client = SendblueAPI(
    api_key=os.environ.get("SENDBLUE_API_API_KEY"),  # This is the default and can be omitted
    api_secret=os.environ.get("SENDBLUE_API_API_SECRET"),  # This is the default and can be omitted
)
contact = client.contacts.delete(
    "+1234567890",
)
print(contact.status)
```

## Domain Types

### Contact

- `class Contact: …`

  - `assigned_to_email: Optional[str]`

    Email of assigned user

  - `company_name: Optional[str]`

    Company name

  - `created_at: Optional[datetime]`

    When the contact was created

  - `custom_variables: Optional[Dict[str, str]]`

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

  - `first_name: Optional[str]`

    First name

  - `last_name: Optional[str]`

    Last name

  - `phone: Optional[str]`

    Phone number in E.164 format

  - `sendblue_number: Optional[str]`

    Associated Sendblue phone number

  - `tags: Optional[List[str]]`

    Tags associated with the contact

  - `verified: Optional[bool]`

    Whether the contact is verified

# Bulk

## Delete

`contacts.bulk.delete(BulkDeleteParams**kwargs)  -> BulkDeleteResponse`

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

Delete multiple contacts by their IDs

### Parameters

- `contact_ids: SequenceNotStr[str]`

  Array of phone numbers in E.164 format to delete

### Returns

- `class BulkDeleteResponse: …`

  - `amount: Optional[int]`

    Number of contacts deleted

  - `status: Optional[str]`

### Example

```python
import os
from sendblue_api import SendblueAPI

client = SendblueAPI(
    api_key=os.environ.get("SENDBLUE_API_API_KEY"),  # This is the default and can be omitted
    api_secret=os.environ.get("SENDBLUE_API_API_SECRET"),  # This is the default and can be omitted
)
bulk = client.contacts.bulk.delete(
    contact_ids=["+1234567890", "+0987654321"],
)
print(bulk.amount)
```

## Create

`contacts.bulk.create(BulkCreateParams**kwargs)  -> BulkCreateResponse`

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

Create multiple contacts in bulk

### Parameters

- `contacts: Iterable[Contact]`

  - `phone: str`

    Phone number in E.164 format

  - `company_name: Optional[str]`

    Company name

  - `custom_variables: Optional[Dict[str, str]]`

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

  - `first_name: Optional[str]`

    Contact's first name

  - `last_name: Optional[str]`

    Contact's last name

  - `tags: Optional[SequenceNotStr[str]]`

### Returns

- `class BulkCreateResponse: …`

  - `contacts: Optional[List[Contact]]`

    - `assigned_to_email: Optional[str]`

      Email of assigned user

    - `company_name: Optional[str]`

      Company name

    - `created_at: Optional[datetime]`

      When the contact was created

    - `custom_variables: Optional[Dict[str, str]]`

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

    - `first_name: Optional[str]`

      First name

    - `last_name: Optional[str]`

      Last name

    - `phone: Optional[str]`

      Phone number in E.164 format

    - `sendblue_number: Optional[str]`

      Associated Sendblue phone number

    - `tags: Optional[List[str]]`

      Tags associated with the contact

    - `verified: Optional[bool]`

      Whether the contact is verified

  - `status: Optional[str]`

### Example

```python
import os
from sendblue_api import SendblueAPI

client = SendblueAPI(
    api_key=os.environ.get("SENDBLUE_API_API_KEY"),  # This is the default and can be omitted
    api_secret=os.environ.get("SENDBLUE_API_API_SECRET"),  # This is the default and can be omitted
)
bulk = client.contacts.bulk.create(
    contacts=[{
        "phone": "phone"
    }],
)
print(bulk.contacts)
```