> For the complete documentation index, see [llms.txt](https://outboundpro.gitbook.io/api-v1/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://outboundpro.gitbook.io/api-v1/contact/listar-contatos.md). # Listar contatos ## Listar contatos (paginação) > Lista paginada de contatos (sócios + contatos adicionais cadastrados pelo\ > cliente). É \*\*obrigatório\*\* passar \`lead\_id\` ou \`lead\_hash\` para escopar a\ > um lead específico — sem isso, retorna HTTP 400.\ > \ > \*\*Por quê obrigatório?\*\* Sem escope, a query varreria toda a base de sócios\ > do cliente (pode ter 50k+ linhas em bases grandes), comprometendo a\ > resposta. Praticamente todo uso real precisa de um escope mesmo.\ > \ > \### Quando usar\ > \- \*\*Aba "Contatos" do CRM\*\* — depois que o usuário abre um lead, popula a lista\ > de sócios/contatos pra mostrar telefones e emails.\ > \- \*\*Picker de "quem ligar"\*\* — equipe comercial escolhe contato pra ação\ > (e-mail/WhatsApp), filtrando pelos prospectados (\`prospected=true\`).\ > \- \*\*Sincronização com discador automático\*\*: pega todos contatos com telefone\ > válido + WhatsApp, manda pro Dialer/PowerDialer fazer rotação.\ > \ > \### Quando NÃO usar\ > \- \*\*Pra pegar dados detalhados de UM contato\*\* — use \`/contact/detail?id=X\` direto.\ > \ > \### Casos de uso reais\ > \- \*\*Salesforce → discador\*\*: ao ativar "iniciar prospecção", busca contatos com\ > \`prospected=true\`, envia primeiros 10 pra fila do discador automático.\ > \- \*\*WhatsApp Business\*\*: ao receber mensagem de um número desconhecido, busca\ > contatos do lead (via CNPJ no campo customizado) pra identificar quem é.\ > \- \*\*Relatório\*\*: lista todos contatos com email, exporta CSV pra análise no\ > BI sem precisar passar pela tela do OutboundPro.
```json {"openapi":"3.0.3","info":{"title":"OutboundPro API","version":"2.0.0"},"tags":[{"name":"Contact","description":"**Sócios e contatos de empresas** (`emp_socio` no banco interno).\nOperações completas: listar, criar, editar, marcar como principal,\ninferir e verificar e-mails, verificar WhatsApp, buscar dados privados\n(com créditos), e listar outras empresas onde o contato é sócio.\n\n### Conceitos chave\n- **Contato principal** (`is_primary_contact`): cada empresa tem 1 contato\n marcado como principal. `set-primary` automaticamente despromove o anterior.\n- **Prospectado** (`is_prospected`): flag de \"este contato vai entrar no\n funil de prospecção\". Marcar/desmarcar via `toggle-save`.\n- **Inferência de e-mail**: gera candidato a e-mail baseado em nome do contato\n + domínio do website da empresa (ex.: `joao.silva@empresa.com.br`),\n com score de confiança. **Não envia teste** — apenas predição.\n- **Verificação de e-mail**: probe DNS + SMTP nos e-mails cadastrados, retorna\n `status` (1=pending, 2=valid, 3=invalid).\n- **Verificação de WhatsApp**: testa cada número, retorna `whatsapp: true/false`\n + `whatsapp_name` e `whatsapp_photo` se disponível.\n- **Dados privados** (`find-private-data`): **consome créditos pagos**, busca\n telefones/emails em serviços externos (Unitfour Intouch, etc.). Verifique\n saldo antes.\n\n### Performance\nEndpoint `contact/list` sem filtro varre toda a tabela `empresa_socio` —\nuse `lead_id` ou `lead_hash` para escopo restrito (recomendado).\n"}],"servers":[{"url":"https://app.outboundpro.com.br/api","description":"Produção"}],"security":[{"TokenAuth":[]}],"components":{"securitySchemes":{"TokenAuth":{"type":"apiKey","in":"header","name":"Token","description":"Chave privada do cliente (`cli_chave_privada`). Formato UUID v4\n(36 caracteres com hífens). Aceita header em qualquer case\n(`Token`, `token`, `TOKEN`).\n"}},"schemas":{"Contact":{"type":"object","properties":{"id":{"type":"integer","description":"ID interno do contato (`emso_codigo`)."},"name":{"type":"string"},"document":{"type":"string","description":"CPF do contato (mascarado parcialmente em sócios da Receita)."},"qualification":{"type":"string","description":"Qualificação (ex.: Sócio-Administrador, Diretor, Procurador)."},"age_range":{"type":"string"},"partnership_entry_date":{"type":"string","format":"date","description":"Data de entrada na sociedade (para sócios)."},"linkedin":{"type":"string","format":"uri"},"facebook":{"type":"string","format":"uri"},"instagram":{"type":"string","format":"uri"},"is_primary_contact":{"type":"boolean","description":"Marcação de contato principal da empresa."},"is_prospected":{"type":"boolean","description":"Marcação de \"vai entrar no funil de prospecção\"."},"is_manual_registration":{"type":"boolean","description":"Se o contato foi cadastrado manualmente (não veio da Receita).\nÚtil para distinguir dados oficiais de complementares.\n"},"custom_fields":{"type":"object","description":"Campos personalizados configurados pelo cliente (livre).","additionalProperties":true},"phones":{"type":"array","items":{"$ref":"#/components/schemas/Phone"}},"emails":{"type":"array","items":{"$ref":"#/components/schemas/Email"}},"inferred_email":{"type":"object","nullable":true,"description":"Resultado da última inferência de e-mail (se houver).","properties":{"full_name":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"inferred_email":{"type":"string","format":"email"},"score":{"type":"integer","minimum":0,"maximum":100,"description":"Confiança da inferência (0-100)."},"site":{"type":"string","description":"Domínio usado na composição (do website da empresa)."},"domain_catch_all":{"type":"boolean","description":"Se o domínio aceita catch-all (toda inferência válida — útil saber para evitar bounces)."},"linkedin":{"type":"string","nullable":true},"twitter":{"type":"string","nullable":true}}},"company":{"type":"object","description":"Sub-objeto resumido da empresa do contato.","properties":{"id":{"type":"integer"},"hash":{"type":"string"},"cnpj":{"type":"string"},"company_name":{"type":"string"},"trade_name":{"type":"string"}}}}},"Phone":{"type":"object","properties":{"id":{"type":"integer","description":"ID interno do telefone (`est_codigo`)."},"number":{"type":"string","description":"Número sem máscara, com DDD."},"type":{"type":"string","enum":["CELULAR","FIXO"]},"whatsapp":{"type":"boolean","description":"Se o número está conectado ao WhatsApp (resultado da última verificação)."},"valid":{"type":"boolean","description":"Se foi validado por algum probe (DNS/portabilidade)."},"priority":{"type":"integer","description":"Ordem de exibição (1 = principal)."},"source":{"type":"string","description":"Origem do dado (`receita`, `manual`, `intouch`, etc.)."}}},"Email":{"type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string","format":"email"},"valid":{"type":"boolean"},"priority":{"type":"integer"},"source":{"type":"string"}}},"ErrorResponse":{"type":"object","required":["response"],"properties":{"response":{"type":"string","enum":["error"]},"mensagem":{"type":"string","description":"Descrição do erro em pt-BR. Família Contact usa `message` (legado)."},"message":{"type":"string","description":"Equivalente inglês de `mensagem`, usado pela família Contact."}}}},"responses":{"BadRequest":{"description":"Parâmetro obrigatório ausente ou em formato inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Token ausente, inválido ou cliente inativo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/contact/list":{"get":{"tags":["Contact"],"summary":"Listar contatos (paginação)","operationId":"contactList","description":"Lista paginada de contatos (sócios + contatos adicionais cadastrados pelo\ncliente). É **obrigatório** passar `lead_id` ou `lead_hash` para escopar a\num lead específico — sem isso, retorna HTTP 400.\n\n**Por quê obrigatório?** Sem escope, a query varreria toda a base de sócios\ndo cliente (pode ter 50k+ linhas em bases grandes), comprometendo a\nresposta. Praticamente todo uso real precisa de um escope mesmo.\n\n### Quando usar\n- **Aba \"Contatos\" do CRM** — depois que o usuário abre um lead, popula a lista\n de sócios/contatos pra mostrar telefones e emails.\n- **Picker de \"quem ligar\"** — equipe comercial escolhe contato pra ação\n (e-mail/WhatsApp), filtrando pelos prospectados (`prospected=true`).\n- **Sincronização com discador automático**: pega todos contatos com telefone\n válido + WhatsApp, manda pro Dialer/PowerDialer fazer rotação.\n\n### Quando NÃO usar\n- **Pra pegar dados detalhados de UM contato** — use `/contact/detail?id=X` direto.\n\n### Casos de uso reais\n- **Salesforce → discador**: ao ativar \"iniciar prospecção\", busca contatos com\n `prospected=true`, envia primeiros 10 pra fila do discador automático.\n- **WhatsApp Business**: ao receber mensagem de um número desconhecido, busca\n contatos do lead (via CNPJ no campo customizado) pra identificar quem é.\n- **Relatório**: lista todos contatos com email, exporta CSV pra análise no\n BI sem precisar passar pela tela do OutboundPro.\n","parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1,"minimum":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"in":"query","name":"order_by","schema":{"type":"string","default":"emso_nome"}},{"in":"query","name":"direction","schema":{"type":"string","enum":["ASC","DESC"],"default":"ASC"}},{"in":"query","name":"lead_id","schema":{"type":"integer"},"description":"ID do lead pra escopar. **Obrigatório (ou lead_hash)**."},{"in":"query","name":"lead_hash","schema":{"type":"string"},"description":"Hash do lead pra escopar (alternativa a lead_id). **Obrigatório (ou lead_id)**."},{"in":"query","name":"prospected","schema":{"type":"string","enum":["true","false","1","0","S","N"]},"description":"Filtra prospectados (true) ou não (false)."}],"responses":{"200":{"description":"Página de contatos.","content":{"application/json":{"schema":{"type":"object","properties":{"response":{"type":"string","enum":["success"]},"total":{"type":"integer"},"page":{"type":"integer"},"limit":{"type":"integer"},"pages":{"type":"integer"},"contacts":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```