# contacts.list Listar contatos. Contatos da conta atual, só os que o membro pode ver (administrador vê todos; os demais, os de conversas nos números liberados e os que criou). Contatos na lixeira nunca aparecem. Filtros: `q` (busca em nome, telefone, e-mail e instagram), `filter` (segmento: lista de nós no formato do construtor de segmentos; grupo = `{id, field: "children", operator: "childrenAnd"|"childrenOr"}` e as condições apontam o grupo em `parentId`; nós sem `parentId` se combinam com E; `negation: true` inverte; valor em `valueString`, `valueNumber`, `valueDate` (AAAA-MM-DD ou ISO), `valueBool` ou `valueUuid`, e listas como JSON em `valueString`). Campos: `name`, `email`, `email_secondary`, `phone`, `instagram`, `linkedin`, `document`, `city`, `state`, `profession`, `language`, `gender`, `birthday`, `created_at`, `updated_at`, `last_activity_at`, `origin_kind`, `ad_id`, `campaign`, `tag`, `list`, `channel` (id do número), `opt_in`/`opt_out` (canal), `temperature`, `temperature_band`, `score`, `score_tier`, `open_opportunities`, `is_customer`, `lgpd`, `email_status` e `cf:`. Operadores: `contains`, `equals`, `startsWith`, `endsWith`, `isNotEmpty`, `greaterThan`, `greaterThanOrEqual`, `lessThan`, `lessThanOrEqual`, `inLast`/`moreThan` (dias, em `valueNumber`) e `in`. Campo ou operador fora do catálogo dá `invalid_input`. Os filtros antigos continuam: `origin` (`ad` = primeira indicação de anúncio; `organic` = todo o resto), `adId` e `channelId`, combinados com E. Ordenação `sort: {key, dir}`: `created` (padrão, mais novo primeiro), `temperature`, `score`, `opportunities`, `name`, `last_activity`; vazios por último. Paginação por número de página (`page` a partir de 1, `perPage` 20, 50 ou 100) ou por `cursor` (`nextCursor`, tamanho em `limit`; só com a ordenação padrão). `page` e `cursor` juntos dão `invalid_input`. `total` conta tudo que casa com os filtros, sem o cursor. Cada item traz o que a tabela de contatos mostra: código, origem (`kind` entre `ad`, `organic`, `manual`, `import`, `integration`, `instagram`, `form`, `api`; anúncio e campanha só com consulta à Meta `ok`), indicadores (temperatura e score `null` = ainda sem cálculo), oportunidades abertas, cliente, canais (opt-in por canal: `opted_in`, `opted_out` ou `none` = sem registro, que vale "pode receber"; `hasConversation` só para whatsapp e instagram), tags, tags de sistema (último momento de cada tipo de atividade, mais recente primeiro), campos personalizados por id e as colunas de cadastro. `emailStatus` fica `unverified` até existir verificação real; `possibleFraud` é sempre `null` (sem fonte). - Endpoint: `POST https://app.atomiks.com.br/api/v1/contacts.list` (corpo JSON) - Quem pode chamar: membro da conta - Escopo da chave: `contacts:read` - Grava dados: não - Pela chave de API: sim - Ferramenta MCP: `contacts_list` - Ficha em JSON: `https://app.atomiks.com.br/api/v1/openapi.json` (operationId `contacts.list`) ## Entrada | Campo | Tipo | Obrigatório | Nota | |---|---|---|---| | `origin` | "ad" \| "organic" | não | | | `adId` | string | não | | | `channelId` | string (uuid) | não | | | `q` | string | não | | | `limit` | integer | não | | | `cursor` | string | não | | | `page` | integer | não | | | `perPage` | 20 \| 50 \| 100 | não | | | `filter` | object[] | não | | | `sort` | object | não | |
JSON Schema ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "origin": { "type": "string", "enum": [ "ad", "organic" ] }, "adId": { "type": "string", "maxLength": 100 }, "channelId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "q": { "type": "string", "maxLength": 100 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string", "maxLength": 300 }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "perPage": { "anyOf": [ { "type": "number", "const": 20 }, { "type": "number", "const": 50 }, { "type": "number", "const": 100 } ] }, "filter": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 64 }, "order": { "type": "integer", "minimum": 0, "maximum": 1000 }, "field": { "type": "string", "maxLength": 60 }, "operator": { "type": "string", "maxLength": 30 }, "negation": { "default": false, "type": "boolean" }, "parentId": { "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "valueString": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "valueNumber": { "type": [ "number", "null" ] }, "valueDate": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "valueBool": { "type": [ "boolean", "null" ] }, "valueUuid": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] } }, "required": [ "field", "operator" ], "additionalProperties": false } }, "sort": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "created", "temperature", "score", "opportunities", "name", "last_activity" ] }, "dir": { "default": "desc", "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "key" ] } } } ```
## Exemplo ```bash curl -X POST https://app.atomiks.com.br/api/v1/contacts.list \ -H "Authorization: Bearer $ATOMIKS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"page":1,"perPage":20,"sort":{"key":"temperature","dir":"desc"},"filter":[{"field":"tag","operator":"in","negation":false,"valueString":"[\"00000000-0000-0000-0000-000000000000\"]"},{"field":"temperature","operator":"greaterThanOrEqual","negation":false,"valueNumber":60}]}' ``` CLI: ```bash node cli/atomiks.mjs contacts.list --json '{"page":1,"perPage":20,"sort":{"key":"temperature","dir":"desc"},"filter":[{"field":"tag","operator":"in","negation":false,"valueString":"[\"00000000-0000-0000-0000-000000000000\"]"},{"field":"temperature","operator":"greaterThanOrEqual","negation":false,"valueNumber":60}]}' ``` MCP: ferramenta `contacts_list` com a mesma entrada. ## Saída Sucesso: `{"data": ...}` com o formato abaixo. ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "firstSeenAt": { "type": "string" }, "origin": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "ad", "organic", "manual", "import", "integration", "instagram", "form", "api" ] }, "detail": { "type": [ "string", "null" ] }, "adId": { "type": [ "string", "null" ] }, "adName": { "type": [ "string", "null" ] }, "campaignName": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] } }, "required": [ "kind", "detail", "adId", "adName", "campaignName", "headline" ], "additionalProperties": false }, "code": { "type": [ "number", "null" ] }, "email": { "type": [ "string", "null" ] }, "emailStatus": { "type": "string", "enum": [ "unverified", "valid", "invalid", "bounced", "unsubscribed" ] }, "instagram": { "type": [ "string", "null" ] }, "telegram": { "type": [ "string", "null" ] }, "document": { "type": [ "string", "null" ] }, "temperature": { "type": [ "number", "null" ] }, "temperatureBand": { "anyOf": [ { "type": "string", "enum": [ "cold", "warm", "hot" ] }, { "type": "null" } ] }, "temperatureTrend": { "type": [ "number", "null" ] }, "temperatureUpdatedAt": { "type": [ "string", "null" ] }, "score": { "type": [ "number", "null" ] }, "scoreTier": { "anyOf": [ { "type": "string", "enum": [ "low", "medium", "high" ] }, { "type": "null" } ] }, "openOpportunities": { "type": "number" }, "isCustomer": { "type": "boolean" }, "lastActivityAt": { "type": [ "string", "null" ] }, "channels": { "type": "array", "items": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "whatsapp", "instagram", "email", "sms", "telegram", "voice" ] }, "consent": { "type": "string", "enum": [ "opted_in", "opted_out", "none" ] }, "hasConversation": { "type": "boolean" } }, "required": [ "channel", "consent", "hasConversation" ], "additionalProperties": false } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string" } }, "required": [ "id", "name", "color" ], "additionalProperties": false } }, "systemTags": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "at": { "type": "string" } }, "required": [ "key", "label", "at" ], "additionalProperties": false } }, "customFields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "emailSecondary": { "type": [ "string", "null" ] }, "linkedin": { "type": [ "string", "null" ] }, "profession": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "gender": { "anyOf": [ { "type": "string", "enum": [ "male", "female", "other" ] }, { "type": "null" } ] }, "birthday": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "address": { "anyOf": [ { "type": "object", "properties": { "cep": { "type": "string" }, "rua": { "type": "string" }, "numero": { "type": "string" }, "complemento": { "type": "string" }, "bairro": { "type": "string" }, "cidade": { "type": "string" }, "estado": { "type": "string" }, "pais": { "type": "string" } }, "additionalProperties": false }, { "type": "null" } ] }, "lgpdConsentAt": { "type": [ "string", "null" ] }, "lgpdSource": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" }, "possibleFraud": { "type": "null" } }, "required": [ "id", "name", "phone", "firstSeenAt", "origin", "code", "email", "emailStatus", "instagram", "telegram", "document", "temperature", "temperatureBand", "temperatureTrend", "temperatureUpdatedAt", "score", "scoreTier", "openOpportunities", "isCustomer", "lastActivityAt", "channels", "tags", "systemTags", "customFields", "emailSecondary", "linkedin", "profession", "language", "gender", "birthday", "city", "state", "address", "lgpdConsentAt", "lgpdSource", "updatedAt", "possibleFraud" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] }, "total": { "type": "number" } }, "required": [ "items", "nextCursor", "total" ], "additionalProperties": false } ``` ## Erros `{"error": {"code", "message", "requestId"}}`. Códigos: `invalid_input` (400), `unauthorized` (401), `forbidden` / `account_pending` / `scope_missing` (403), `not_found` (404), `limit_reached` (409), `internal` (500).