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:<id do campo personalizado>. 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(operationIdcontacts.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
{
"$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
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:
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.
{
"$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).