---
title: "Contacts API"
description: "List, create, update and archive contacts with workspace-scoped keys."
url: "https://documentation.verbatik.com/api/contacts/"
---

# Contacts API

List, create, update and archive contacts with workspace-scoped keys.

Endpoint: `/api/v1/workspaces/WORKSPACE_ID/contacts`. Read requests need `contacts:read`; writes need `contacts:write`.

## List contacts

```bash
curl 'https://dashboard.verbatik.com/api/v1/workspaces/WORKSPACE_ID/contacts' \
  -H "Authorization: Bearer $VERBATIK_API_KEY"
```

Returns `{ "data": [...] }`. This route does not define cursor or page query parameters; use the returned collection rather than inventing pagination parameters.

## Create a contact

```bash
curl -X POST 'https://dashboard.verbatik.com/api/v1/workspaces/WORKSPACE_ID/contacts' \
  -H "Authorization: Bearer $VERBATIK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"firstName":"Alex","lastName":"Rivera","phone":"+12025550123","email":"alex@example.com","tags":["website-inquiry"],"language":"en","consent":"unknown","doNotCall":false,"fields":{}}'
```

Success is `201` with `{ "data": { ...contact } }`. Use a phone number you are authorized to store; the example is illustrative and must not be dialed.

## Supported fields

- `firstName`, `lastName`: up to 160 characters each.
- `phone`: blank or E.164, such as `+12025550123`.
- `email`: blank or a valid email address.
- `tags`: up to 50 strings, each up to 100 characters.
- `language`: a supported agent language code; defaults to `en`.
- `consent`: `unknown`, `granted` or `revoked`; defaults to `unknown`.
- `doNotCall`: boolean, default false.
- `fields`: custom-field values keyed by configured field names. Configure the field definitions in Contacts before sending values.

Do not set consent to granted merely because a number was imported. Record the permission your business has actually obtained.

## Update and archive

Send `PATCH` to the same URL with an `id` and only changed fields, for example:

```json
{"id":"CONTACT_ID","tags":["website-inquiry","staff-follow-up"],"doNotCall":true}
```

Send `DELETE /contacts?id=CONTACT_ID` to archive a contact. The success body is `{ "data": { "id": "CONTACT_ID", "archived": true } }`. These routes do not provide general create-request idempotency; check the response and stored record before repeating an uncertain creation.