> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telaven.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts

> Keep your customer list in step with your own systems, so your campaigns always reach the right people.

Contacts are shared by SMS, WhatsApp, email and the CRM. Group them two ways:

* **Lists**: a contact belongs to a list, for example *Customers* or *Event leads*.
* **Tags**: lower-case labels such as `vip` or `city`. A contact can carry many.

Campaigns can target lists, tags or both.

## Add a contact

```bash theme={null}
curl -X POST https://app.telaven.com/api/v1/contacts \
  -H "Authorization: Bearer $TELAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "0712345678",
    "name": "Jane Wanjiku",
    "email": "jane@example.com",
    "listId": "c51e…",
    "tags": ["vip", "city"]
  }'
```

**phone** `string`

Phone number. A contact needs a phone or a name.

**name** `string`

Full name. You can send `firstName` and `lastName` instead.

**email** `string`

Email address.

**listId** `string`

The contact list to add them to.

**subscriptionType** `string`

`marketing` (default), `non-marketing` or `unsubscribed`.

**tags** `string[]`

Lower-case labels.

## Lists

| Call | Does |
| - | - |
| [`POST /sms/contact-lists`](https://docs.telaven.com/api-reference/contacts/create-contact-list) | Creates an empty list. Add people with `listId` on Create contact. |
| [`GET /sms/contact-lists`](https://docs.telaven.com/api-reference/contacts/list-contact-lists) | Lists your lists, with contact counts. |
| [`GET /sms/contact-lists/{id}`](https://docs.telaven.com/api-reference/contacts/get-contact-list) | One list, with how many contacts have a phone, an email or both. |
| [`PATCH /sms/contact-lists/{id}`](https://docs.telaven.com/api-reference/contacts/update-contact-list) | Renames a list or changes its description. |
| [`DELETE /sms/contact-lists/{id}`](https://docs.telaven.com/api-reference/contacts/delete-contact-list) | Deletes a list **and the contacts in it**. |

> [!TIP]
>
> Syncing a large customer base? Page through [`GET /contacts`](https://docs.telaven.com/api-reference/contacts/list-contacts) with `listId` and add only the contacts that aren't there yet. For a one-off import of thousands, the CSV import in the dashboard is quicker.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.