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

# Contacts

> API reference for Essal Sales contacts — create, search, update, merge, and delete contact records.

## List Contacts

`GET /v1/sales/contacts`

**Query Parameters**

| Parameter  | Type    | Description                                  |
| ---------- | ------- | -------------------------------------------- |
| `q`        | string  | Full-text search across name, email, company |
| `owner_id` | string  | Filter by assigned owner                     |
| `limit`    | integer | Results per page                             |

***

## Get a Contact

`GET /v1/sales/contacts/{id}`

***

## Create a Contact

`POST /v1/sales/contacts`

```json theme={null}
{
  "display_name": "Jane Smith",
  "email": "jane@acmecorp.com",
  "organization_name": "Acme Corp",
  "phone": "+44 7700 900123",
  "custom_fields": { "region": "EMEA", "account_tier": "enterprise" }
}
```

**Response** — `201 Created`

```json theme={null}
{
  "id": "cnt_01HXYZ9999",
  "display_name": "Jane Smith",
  "email": "jane@acmecorp.com",
  "created_at": "2026-07-10T09:00:00Z"
}
```

***

## Update a Contact

`PATCH /v1/sales/contacts/{id}`

```json theme={null}
{ "phone": "+44 7700 900456", "custom_fields": { "account_tier": "strategic" } }
```

***

## Merge Duplicates

`POST /v1/sales/contacts/merge`

Merge two contact records, keeping one as the canonical record:

```json theme={null}
{
  "primary_id": "cnt_01HXYZ9999",
  "duplicate_id": "cnt_01HXYZ8888"
}
```

All deals, activities, and linked resources attached to the duplicate are re-associated with the primary contact. The duplicate is then archived.

***

## Delete a Contact

`DELETE /v1/sales/contacts/{id}`

Soft-deletes the contact. Pass `?hard=true` for permanent deletion.