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

# Contacts API

List, get, create, upsert, and update contacts.

# Contacts API

Contacts represent customers or users.

```txt
/api/v1/projects/:projectId/contacts
```

## List Contacts

```bash
curl "https://api.rogeriq.com/api/v1/projects/prj_123/contacts?q=ada" \
  -H "Authorization: Bearer riq_your_key"
```

Query parameters:

| Parameter | Description |
| --- | --- |
| `q` | Search name or email. |
| `email` | Exact email filter. |
| `external_id` | Exact external ID filter. |
| `cursor` | Pagination cursor. |
| `limit` | Page size. |

## Create or Upsert Contact

If an existing contact matches the upsert behavior, RogerIQ updates instead of creating a duplicate.

```bash
curl https://api.rogeriq.com/api/v1/projects/prj_123/contacts \
  -H "Authorization: Bearer riq_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "phone": "+15551234567",
    "company": "Analytical Engines Ltd",
    "job_title": "Founder",
    "external_id": "cus_123",
    "metadata": {
      "plan": "pro",
      "mrr": 499
    }
  }'
```

At least one of `email`, `name`, or `external_id` is required.

## Get Contact

```bash
curl https://api.rogeriq.com/api/v1/projects/prj_123/contacts/ct_123 \
  -H "Authorization: Bearer riq_your_key"
```

## Update Contact

```bash
curl -X PATCH https://api.rogeriq.com/api/v1/projects/prj_123/contacts/ct_123 \
  -H "Authorization: Bearer riq_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "plan": "enterprise",
      "renewal_date": "2026-09-01"
    }
  }'
```

Use `external_id` for stable product identity. Email addresses can change.