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

# Contacts

Your organization's contact book. Contacts power SMS personalization and caller matching.

## List contacts

`GET /v1/contacts` — scope `contacts:read`

Lists contacts, newest first, with standard [pagination](/api-reference/rate-limits-errors-and-pagination.md).

## Get a contact

`GET /v1/contacts/{id}` — scope `contacts:read`

Fetches one contact by numeric id.

## Create a contact

`POST /v1/contacts` — scope `contacts:write`

Creates a contact — or **merges into an existing one**. If a contact already exists with the same phone (matched on the last 10 digits, any format) or email, the fields you send are merged into it and you get `200` with the existing contact; a genuinely new contact returns `201`. No duplicates either way.

| Field                                 | Type      | Notes                                      |
| ------------------------------------- | --------- | ------------------------------------------ |
| `phone`                               | string    | Stored normalized. The primary dedupe key  |
| `email`                               | string    | Secondary dedupe key when no phone is sent |
| `firstName`, `lastName`               | string    |                                            |
| `address`, `city`, `state`, `zipCode` | string    |                                            |
| `tags`                                | string\[] |                                            |
| `status`, `notes`                     | string    |                                            |

```bash
curl -X POST https://dashboard.limephone.io/api/v1/contacts \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ada",
    "lastName": "Lovelace",
    "phone": "+14155550134",
    "email": "ada@example.com",
    "tags": ["vip"]
  }'
```

```javascript
// Node.js — create a contact
const res = await fetch('https://dashboard.limephone.io/api/v1/contacts', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LIMEPHONE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    firstName: 'Ada',
    lastName: 'Lovelace',
    phone: '+14155550134',
    email: 'ada@example.com',
  }),
});
const contact = await res.json();
```

## Update a contact

`PATCH /v1/contacts/{id}` — scope `contacts:write`

Updates a contact. Only the fields listed under Create are writable; anything else in the body is ignored. Send only what changes.

```bash
curl -X PATCH https://dashboard.limephone.io/api/v1/contacts/311 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "notes": "Prefers SMS over calls" }'
```

## Delete a contact

`DELETE /v1/contacts/{id}` — scope `contacts:write`

Deletes a contact permanently. Returns `204` with no body. This cannot be undone.