ReferênciaContacts
Contacts
Criar, buscar, upsert por email/telefone.
Crie com pelo menos display_name. Email é recomendado. Telefone com menos de 7 ou mais de 15 dígitos é 400. PATCH não muda email nem 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
| Parâmetro | Tipo | Notas |
|---|---|---|
| string | Lookup do email primário. Miss é data: [], não 404. | |
| phone | string | Lookup do telefone primário. Miss é data: []. |
| q | string | Busca nome, email, phone e empresa. |
| limit / cursor | number / string | Página de cursor. limit 1–100, default 20. |
Campos
| Campo | Tipo | Create | PATCH | Notas |
|---|---|---|---|---|
| id | UUID | — | não | Imutável. |
| display_name | string | null | sim | sim | Obrigatório no create. Parte em first + last. |
| string | null | sim | não | Email primário. Só no create. | |
| phone | string | null | sim | não | 7–15 dígitos. Day 1 grava como BR +55. |
| company_id | UUID | null | sim | sim | Empresa desta org, ou null. |
| owner_id | UUID | null | sim | sim | Mesmo id de GET /members. |
| tag_ids | UUID[] | sim | sim | Replace total. [] limpa. |
| created_at / updated_at | datetime | — | não | ISO-8601 UTC. |
Upsert casa email, depois phone. created: true e 201 na inserção; created: false e 200 no update. Email/phone não mudam no update. Não precisa de Idempotency-Key para não duplicar — o upsert é o contrato de identidade.