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

# Contacts

> Create, read, update, and delete contact records.

Base path: `https://api.recepta.ai/api/v1/api/contacts`

All endpoints require an [API key](/api-reference/authentication) in `x-api-key`, and the permission noted on each.

## List contacts

<ParamField path="GET /api/v1/api/contacts" type="contacts:read" required />

| Query param | Type    | Default | Notes                                      |
| ----------- | ------- | ------- | ------------------------------------------ |
| `page`      | integer | `1`     | Page number                                |
| `limit`     | integer | `50`    | Items per page                             |
| `search`    | string  | —       | Matches name, email, or phone              |
| `source`    | enum    | —       | `MANUAL`, `FACEBOOK`, `CSV`, `API`, `CALL` |
| `status`    | string  | —       | Filter by status                           |
| `tags`      | string  | —       | Filter by tag                              |

```bash theme={null}
curl "https://api.recepta.ai/api/v1/api/contacts?source=FACEBOOK&limit=50" \
  -H "x-api-key: $RECEPTA_API_KEY"
```

## Get a contact

<ParamField path="GET /api/v1/api/contacts/{clientId}" type="contacts:read" required />

Returns `404` if the contact isn't in your workspace.

## Create a contact

<ParamField path="POST /api/v1/api/contacts" type="contacts:create" required />

<ResponseField name="firstName" type="string" />

<ResponseField name="lastName" type="string" />

<ResponseField name="fullName" type="string">
  Use instead of first and last name where you only have a single field.
</ResponseField>

<ResponseField name="email" type="string" />

<ResponseField name="phone" type="string">
  Normalized to E.164 automatically, so mixed input formats are accepted.
</ResponseField>

<ResponseField name="source" type="enum" default="API">
  One of `MANUAL`, `FACEBOOK`, `CSV`, `API`, `CALL`.
</ResponseField>

<ResponseField name="tags" type="string[]">
  How you segment for [campaigns](/outbound/campaigns). Tag on creation — retrofitting tags later is painful.
</ResponseField>

<ResponseField name="status" type="string" />

<ResponseField name="notes" type="string" />

<ResponseField name="company_name" type="string" />

<ResponseField name="address" type="string" />

<ResponseField name="city" type="string" />

<ResponseField name="state" type="string" />

<ResponseField name="zipCode" type="string" />

<ResponseField name="country" type="string" />

<ResponseField name="customFields" type="object">
  Anything specific to your business — equipment model, plan tier, gate code. Usable for personalization in [sequences](/outbound/sequences).
</ResponseField>

```bash theme={null}
curl -X POST https://api.recepta.ai/api/v1/api/contacts \
  -H "x-api-key: $RECEPTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Dana",
    "lastName": "Reyes",
    "phone": "+14155551234",
    "email": "dana@example.com",
    "source": "API",
    "tags": ["quotes-q3"],
    "customFields": { "unitModel": "AO-50G" }
  }'
```

Returns `201` on success.

## Update a contact

<ParamField path="PUT /api/v1/api/contacts/{clientId}" type="contacts:update" required />

Accepts the same fields as create.

```bash theme={null}
curl -X PUT https://api.recepta.ai/api/v1/api/contacts/CONTACT_ID \
  -H "x-api-key: $RECEPTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "booked", "tags": ["quotes-q3", "won"] }'
```

## Delete a contact

<ParamField path="DELETE /api/v1/api/contacts/{clientId}" type="contacts:delete" required />

<Warning>
  Deletion is permanent. Deleting a contact does **not** clear a suppression — someone who opted out of SMS or email stays suppressed, which is the intended behavior. Re-creating them will not re-enable messaging.
</Warning>

## Keeping systems in sync

Subscribe to `contact.created` and `contact.updated` rather than polling this endpoint. See [Webhooks](/api-reference/webhooks).

<Tip>
  Before bulk-creating contacts, check whether [CSV import](/outbound/contacts) or a native [CRM integration](/integrations/overview) does the job. Both handle deduplication and mapping you'd otherwise write yourself.
</Tip>