ReferenceContacts
Contacts
Create, search, upsert by email/phone.
Create with at least display_name. Email is recommended. Phone with fewer than 7 or more than 15 digits is 400. PATCH cannot change email or phone.
| HTTP | Path | Scope |
|---|---|---|
| GET | /api/v1/contacts | rest.crm.contacts.read |
| POST | /api/v1/contacts | rest.crm.contacts.write |
| POST | /api/v1/contacts/upsert | rest.crm.contacts.write |
| GET | /api/v1/contacts/{id} | rest.crm.contacts.read |
| PATCH | /api/v1/contacts/{id} | rest.crm.contacts.write |
Query
| Parameter | Type | Notes |
|---|---|---|
| string | Primary email lookup. Miss is data: [], not 404. | |
| phone | string | Primary phone lookup. Miss is data: []. |
| q | string | Full-text name, email, phone and company. |
| limit / cursor | number / string | Cursor page. limit 1–100, default 20. |
Fields
| Field | Type | Create | PATCH | Notes |
|---|---|---|---|---|
| id | UUID | — | não | Immutable. |
| display_name | string | null | sim | sim | Required on create. Split into first + last. |
| string | null | sim | não | Primary email. Create only. | |
| phone | string | null | sim | não | 7–15 digits. Day 1 stores as BR +55. |
| company_id | UUID | null | sim | sim | Company in this org, or null. |
| owner_id | UUID | null | sim | sim | Same id as GET /members. |
| tag_ids | UUID[] | sim | sim | Full replace. [] clears. |
| created_at / updated_at | datetime | — | não | ISO-8601 UTC. |
Upsert matches email, then phone. created: true and 201 on insert; created: false and 200 on update. Email/phone do not change on update. You do not need Idempotency-Key to avoid duplicates — upsert is the identity contract.