> For the complete documentation index, see [llms.txt](https://docs.limecall.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limecall.com/developers/contacts.md).

# Contacts API

Full CRUD over the people who contact you.

| Method   | Path             | Scope            |
| -------- | ---------------- | ---------------- |
| `GET`    | `/contacts`      | `contacts:read`  |
| `GET`    | `/contacts/{id}` | `contacts:read`  |
| `POST`   | `/contacts`      | `contacts:write` |
| `PATCH`  | `/contacts/{id}` | `contacts:write` |
| `DELETE` | `/contacts/{id}` | `contacts:write` |

The only resource in the API with full CRUD.

## List contacts

```bash
curl "https://app.limecall.com/api/v1/contacts?page=1&limit=50" \
  -H "Authorization: Bearer sk_live_..."
```

`page` defaults to `1` and `limit` to `50`. Returns the standard `{ data, pagination }` envelope.

## Fields

Accepted on both `POST` and `PATCH`:

`firstName` · `lastName` · `email` · `phone` · `address` · `city` · `state` · `zipCode` · `tags` · `status` · `notes`

## Create

```bash
curl -X POST https://app.limecall.com/api/v1/contacts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Priya",
    "lastName": "Patel",
    "phone": "+447700900123",
    "email": "priya@example.com",
    "tags": ["import", "leeds"]
  }'
```

Send `phone` in international format. Contacts are matched on phone number throughout LimeCall, so a national-format number creates a duplicate rather than matching the existing person.

## Update

```bash
curl -X PATCH https://app.limecall.com/api/v1/contacts/3310 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"status":"customer","notes":"Signed 12 Sept."}'
```

Send only the fields you are changing.

## Delete

```bash
curl -X DELETE https://app.limecall.com/api/v1/contacts/3310 \
  -H "Authorization: Bearer sk_live_..."
```

{% hint style="warning" %}
Deleting a contact removes the person and the history attached to them, including recordings. This is how an erasure request is honoured — and it is not reversible. See [Security](/account/security.md).
{% endhint %}

## Bulk imports

There is no bulk endpoint. Importing a list means one `POST` per row, so respect the rate limit and back off on `429` rather than firing the whole file at once. See [Errors, pagination & rate limits](/developers/errors-and-rate-limits.md).

For a one-off import, the CSV importer in the dashboard is easier — see [Contacts](/inbox-and-leads/contacts.md).