> 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/company/prospect-company.md). # Prospect Company ## Enriquecer empresa por CNPJ (adiciona se não existir) > Recupera dados completos de uma empresa pelo CNPJ — razão social,\ > nome fantasia, endereço, CNAEs (principal + secundários), sócios e\ > status na Receita Federal.\ > \ > \*\*Comportamento de side-effect:\*\* se a empresa \*\*ainda não existe na sua base\*\*,\ > ela é \*\*automaticamente adicionada\*\* como novo lead, com status configurado como\ > \`status\_inicial\` do cliente (ver \[Status]\(#tag/Status)). Esse é o caso de uso\ > principal: pipelines de prospecção que recebem CNPJs e querem enriquecer +\ > ingerir no funil em uma chamada só.\ > \ > Se já existir, \*\*nenhum INSERT\*\* é feito — você recebe os dados existentes\ > (incluindo edições manuais já aplicadas no painel).\ > \ > \### Quando usar\ > \- Pipeline de enriquecimento (CSV de CNPJs → leads cadastrados).\ > \- Webhook de captura externa (formulário, landing) → ingerir CNPJ.\ > \- Verificação de cadastro de cliente novo (validação de CNPJ).\ > \ > \### Quando NÃO usar\ > \- \*\*Listar empresas já cadastradas\*\* → use \[\`lead/list\`]\(#operation/leadList).\ > \- \*\*Buscar por nome/CNAE/UF\*\* → use \[\`lead/search\`]\(#operation/leadSearch).\ > \- \*\*Detalhe de lead já conhecido (sem novo lookup Receita)\*\* → \[\`lead/detail\`]\(#operation/leadDetail).\ > \ > \### Limites e ressalvas\ > \- Cada lookup pode disparar consulta na base pública (Receita Federal);\ > espere latência média 200–600 ms.\ > \- \*\*Não é idempotente em side-effect\*\*: a primeira chamada cria o lead,\ > chamadas seguintes não duplicam, mas atualizam timestamp.\ > \- \*\*Consome créditos\*\* (futuramente — hoje gratuito) — endpoint potencialmente\ > tarifado por consulta.
```json {"openapi":"3.0.3","info":{"title":"OutboundPro API","version":"2.0.0"},"tags":[{"name":"Company","description":"**Enriquecimento de empresa por CNPJ.** Receba dados completos\n(razão social, endereço, CNAEs, sócios) e adicione automaticamente à sua base\nde leads quando ainda não existir.\n\n### Quando usar\n- Você tem o CNPJ e quer enriquecer com dados estruturados (cadastro, sócios).\n- Quer **adicionar empresa nova à sua base** automaticamente no primeiro lookup.\n- Pipeline de enriquecimento de leads (ex.: cliente envia CSV de CNPJs).\n\n### Quando NÃO usar\n- Listar muitas empresas já cadastradas → use [Lead](#tag/Lead) (`lead/list`).\n- Buscar por nome/razão → use [Lead](#tag/Lead) (`lead/search`).\n- Detalhe de empresa já existente sem novo lookup → use [Lead](#tag/Lead) (`lead/detail`).\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"}},"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"}}}}},"schemas":{"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."}}}}},"paths":{"/company/prospect":{"get":{"tags":["Company"],"summary":"Enriquecer empresa por CNPJ (adiciona se não existir)","operationId":"companyProspect","description":"Recupera dados completos de uma empresa pelo CNPJ — razão social,\nnome fantasia, endereço, CNAEs (principal + secundários), sócios e\nstatus na Receita Federal.\n\n**Comportamento de side-effect:** se a empresa **ainda não existe na sua base**,\nela é **automaticamente adicionada** como novo lead, com status configurado como\n`status_inicial` do cliente (ver [Status](#tag/Status)). Esse é o caso de uso\nprincipal: pipelines de prospecção que recebem CNPJs e querem enriquecer +\ningerir no funil em uma chamada só.\n\nSe já existir, **nenhum INSERT** é feito — você recebe os dados existentes\n(incluindo edições manuais já aplicadas no painel).\n\n### Quando usar\n- Pipeline de enriquecimento (CSV de CNPJs → leads cadastrados).\n- Webhook de captura externa (formulário, landing) → ingerir CNPJ.\n- Verificação de cadastro de cliente novo (validação de CNPJ).\n\n### Quando NÃO usar\n- **Listar empresas já cadastradas** → use [`lead/list`](#operation/leadList).\n- **Buscar por nome/CNAE/UF** → use [`lead/search`](#operation/leadSearch).\n- **Detalhe de lead já conhecido (sem novo lookup Receita)** → [`lead/detail`](#operation/leadDetail).\n\n### Limites e ressalvas\n- Cada lookup pode disparar consulta na base pública (Receita Federal);\n espere latência média 200–600 ms.\n- **Não é idempotente em side-effect**: a primeira chamada cria o lead,\n chamadas seguintes não duplicam, mas atualizam timestamp.\n- **Consome créditos** (futuramente — hoje gratuito) — endpoint potencialmente\n tarifado por consulta.\n","parameters":[{"in":"query","name":"cnpj","required":true,"schema":{"type":"string","minLength":14,"maxLength":14,"pattern":"^\\d{14}$"},"description":"CNPJ sem máscara, 14 dígitos numéricos. Qualquer caractere de formatação\n(`.`, `/`, `-`) é removido pelo servidor antes da consulta — mas envie\nlimpo para evitar surpresas.\n"}],"responses":{"200":{"description":"Empresa encontrada (ou criada se era nova).","content":{"application/json":{"schema":{"type":"object","required":["response","date"],"properties":{"response":{"type":"string","enum":["success"]},"date":{"type":"object","description":"Payload completo da empresa (snake_case interno)."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```