Queries CNAE avançadas para outbound

O problema com listas genéricas

Listas montadas só com CNAE costumam trazer milhares de empresas que não são boas prospects. O resultado: SDR gastando tempo com contas que não fecham.

A solução é combinar múltiplos filtros para recortar o universo antes de exportar.

Filtro 1 — CNAE principal com exclusão

O CNAE principal filtra a atividade core da empresa. Mas muitos CNAEs são amplos demais. Use cnae_exclude para tirar o que não serve.

curl -X POST https://api.orbioapi.com.br/v1/accounts/search \
  -H "Authorization: Bearer $ORBIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "kind": "account_query",
      "spec_version": "2.0",
      "entity": "company",
      "limit": 10,
      "filters": {
        "industry": {
          "cnae_any_of": ["6201-5/01", "6201-5/02"],
          "cnae_exclude": ["6209-1/00"],
          "secondary_cnae_mode": "off"
        }
      },
      "output": {
        "format": "json",
        "fields": ["cnpj", "legal_name", "cnae_primary", "uf"]
      }
    }
  }'

Neste exemplo, trazemos empresas de desenvolvimento de software (6201-5/01 e 6201-5/02) mas excluímos suporte técnico (6209-1/00).

Filtro 2 — CNAE secundário

O CNAE principal nem sempre é o melhor indicador da atividade que interessa. Para incluir empresas onde o CNAE desejado aparece como secundário, use export async com secondary_cnae_mode: "fallback".

"industry": {
  "cnae_any_of": ["7319-0/02"],
  "secondary_cnae_mode": "fallback"
}

Isso funciona em exports (POST /v1/exports). O modo fallback busca primeiro no CNAE principal e, se não encontrar resultados, expande para o secundário. Para buscas sncronas, o modo secundrio fica em off.

Filtro 3 — Porte e tipo

Filtre por tipo de empresa para eliminar ruído:

"company": {
  "registration_status_any_of": [2],
  "company_size_code_any_of": [3, 4, 5],
  "headquarters_only": true
}

• registration_status_any_of: [2] — apenas ativas
• company_size_code_any_of: [3, 4, 5] — média, grande e não informado (exclui micro e pequena)
• headquarters_only: true — apenas matriz, sem filiais duplicadas

Filtro 4 — Geografia com município

Para operações regionais, combine UF com município:

"geo": {
  "uf_any_of": ["SP"],
  "municipality_ibge_any_of": ["3550308"]
}

O código 3550308 é São Paulo capital. Isso é mais preciso que filtrar por UF inteiro.

Filtro 5 — Contato obrigatório

Para outbound que depende de email ou telefone:

"contact": {
  "require_email": true,
  "require_phone": false,
  "require_any_contact": false
}

Use require_email: true para garantir que toda empresa da lista tenha ao menos um email cadastrado.

Combinando tudo

O poder real é na combinação. Um exemplo completo para outbound de SaaS B2B:

curl -X POST https://api.orbioapi.com.br/v1/accounts/search \
  -H "Authorization: Bearer $ORBIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "kind": "account_query",
      "spec_version": "2.0",
      "entity": "company",
      "limit": 50,
      "filters": {
        "industry": {
          "cnae_any_of": ["6201-5/01", "6201-5/02", "6202-3/00"],
          "cnae_exclude": ["6209-1/00", "6311-9/00"],
          "secondary_cnae_mode": "off"
        },
        "geo": {
          "uf_any_of": ["SP", "RJ", "MG"],
          "municipality_ibge_any_of": []
        },
        "company": {
          "registration_status_any_of": [2],
          "company_size_code_any_of": [3, 4, 5],
          "headquarters_only": true,
          "simples_opt_in": null,
          "mei_opt_in": null
        },
        "contact": {
          "require_email": true,
          "require_phone": false,
          "require_any_contact": false
        }
      },
      "sort": [],
      "output": {
        "format": "json",
        "fields": [
          "cnpj", "legal_name", "uf", "municipality_ibge",
          "cnae_primary", "company_size_code",
          "email", "phone1"
        ]
      }
    }
  }'

Essa query traz empresas de software em SP/RJ/MG, de porte médio ou grande, apenas ativas e matrizes, com email disponível.

Dicas de performance

1. Comece com limit: 10 para validar o recorte antes de puxar volumes maiores.
2. Use paginação cursor para listas grandes. Cada resposta traz next_cursor para a página seguinte.
3. Export async para CSV quando a lista passa de 500. Poll GET /v1/exports/{export_id} até status=done e use download_url.
4. Verifique o snapshot na resposta. Ele indica o mês da base usada — essencial para rastreabilidade.

Erros comuns

• CNAE amplo demais: trazer 6201-5 (todos de software) quando você quer só 6201-5/01 (desenvolvimento sob encomenda).
• Esquecer headquarters_only: sem isso, a mesma empresa aparece várias vezes (matriz + filiais).
• Não filtrar inativas: sem registration_status_any_of: [2], a lista inclui empresas baixadas.
• Ignorar o snapshot: sem saber o mês da base, não dá para reproduzir a lista depois.