ReferênciaContatos
Listar contatos
GET /contacts — lista os contatos da organização com busca livre, filtros exatos e sync incremental por data.
GET
/contactsBetaEscopo necessário: contacts:read
Lista os contatos da organização (resolvida pela API key), em ordem de updated_at decrescente. Suporta paginação por limit/offset.
Endpoint
GET https://crm.oficinamartech.com/api/v1/contactsParâmetros de query
| Parâmetro | Tipo | Descrição |
|---|---|---|
q | string (2-200) | Busca livre (case-insensitive) em nome, email e telefone. |
email | string (email) | Filtro exato por email (case-insensitive). |
phone | string | Filtro por telefone em qualquer formato; normalizado para E.164 com variantes do 9º dígito (Brasil). |
source | string | Filtro exato pela origem do contato (ex.: api, whatsapp). |
created_since | date | Somente contatos criados a partir desta data (inclusive). ISO 8601 ou YYYY-MM-DD. |
updated_since | date | Somente contatos atualizados a partir desta data (inclusive). ISO 8601 ou YYYY-MM-DD. |
limit | int (1-100) | Tamanho da página. Default: 50. |
offset | int | Deslocamento da página. Default: 0. |
Sync incremental: para espelhar contatos em outro sistema, guarde o instante da última sincronização e chame GET /contacts?updated_since=<instante> periodicamente. Contatos criados também contam como atualizados.
Exemplo
curl -s "https://crm.oficinamartech.com/api/v1/contacts?q=maria&limit=2" \
-H "Authorization: Bearer crm_live_SEU_PREFIXO_SEU_SEGREDO"Resposta 200
{
"data": [
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"organization_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789",
"name": "Maria Silva",
"email": "maria@example.com",
"phone": "+5511999999999",
"phone_e164": "+5511999999999",
"source": "api",
"custom_fields": { "plano": "Pro" },
"created_at": "2026-06-10T14:03:22.000Z",
"updated_at": "2026-07-01T09:12:45.000Z"
}
],
"pagination": {
"limit": 2,
"offset": 0,
"count": 1,
"has_more": false,
"next_offset": null
}
}Erros
| Status | Código | Quando |
|---|---|---|
400 | — | Query inválida (filtro malformado, data inválida). |
401 | missing_api_key / invalid_api_key | API key ausente, inválida, expirada ou revogada. |
403 | missing_scope | A chave não tem o escopo contacts:read. |
429 | rate_limited | Acima de 120 req/min por chave ou por organização. |
500 | — | Erro interno. |