POST /v1/accounts/search

Base URL: https://api.orbioapi.com.br

Autenticação

Authorization: Bearer <API_KEY>

Body da requisição

Obrigatório: envie spec.

Campos:

spec (object, obrigatório): filtros estruturados (AccountQuerySpec).
limit (int, opcional): 1–50000 (o plano pode limitar).
cursor (string, opcional): paginação.
output (object, opcional):
- format: use json para este endpoint.
- include_explain: inclui explicações no spec.
- fields: lista de campos de saída.

Regras de paginação

Sem cursor: envie spec (e opcionalmente limit/output).
Com cursor:
- spec é obrigatório e deve ser o mesmo spec que gerou o cursor (recomenda-se reusar o spec retornado na resposta anterior).
- Não envie overrides (limit, output).
- Se cursor não corresponder ao spec, a API retorna 422 cursor_mismatch.

Exemplo (spec)

json

Testar

{
  "spec": {
    "kind": "account_query",
    "spec_version": "2.0",
    "entity": "company",
    "limit": 20,
    "filters": {
      "industry": {
        "cnae_any_of": ["6201-5/00"],
        "cnae_exclude": [],
        "secondary_cnae_mode": "off",
        "text_hints": ["software"]
      },
      "geo": {
        "uf_any_of": ["SP"],
        "municipality_ibge_any_of": [],
        "municipality_tom_any_of": []
      },
      "company": {
        "registration_status_any_of": [2],
        "company_size_code_any_of": [],
        "headquarters_only": true,
        "simples_opt_in": null,
        "mei_opt_in": null,
        "started_after": null,
        "started_before": null
      },
      "contact": {
        "require_email": true,
        "require_phone": false,
        "require_any_contact": false
      }
    },
    "sort": [{ "field": "score", "direction": "desc" }],
    "scoring": { "strategy": "balanced", "random_seed": null },
    "output": {
      "format": "json",
      "include_explain": false,
      "fields": ["cnpj", "legal_name", "uf", "municipality_ibge", "cnae_primary"]
    },
    "explain": {
      "assumptions": [],
      "warnings": [],
      "unmapped_constraints": [],
      "confidence": 0.74
    }
  }
}

Resposta (200 OK)

json

Testar

{
  "request_id": "req_01HX...",
  "snapshot": "2026-01",
  "snapshot_date": "2026-01-31",
  "provenance": {
    "rfb_snapshot": "2026-01",
    "ibge_population_year": "not_available",
    "ceis_as_of_date": "not_available"
  },
  "spec": {
    "kind": "account_query",
    "spec_version": "2.0",
    "entity": "company",
    "limit": 20,
    "filters": {
      "industry": {
        "cnae_any_of": ["6201-5/00"],
        "cnae_exclude": [],
        "secondary_cnae_mode": "off",
        "text_hints": ["software"]
      },
      "geo": {
        "uf_any_of": ["SP"],
        "municipality_ibge_any_of": [],
        "municipality_tom_any_of": []
      },
      "company": {
        "registration_status_any_of": [2],
        "company_size_code_any_of": [],
        "headquarters_only": true,
        "simples_opt_in": null,
        "mei_opt_in": null,
        "started_after": null,
        "started_before": null
      },
      "contact": {
        "require_email": true,
        "require_phone": false,
        "require_any_contact": false
      }
    },
    "sort": [{ "field": "score", "direction": "desc" }],
    "scoring": { "strategy": "balanced", "random_seed": null },
    "output": {
      "format": "json",
      "include_explain": false,
      "fields": ["cnpj", "legal_name", "uf", "municipality_ibge", "cnae_primary"]
    },
    "explain": {
      "assumptions": [],
      "warnings": [],
      "unmapped_constraints": [],
      "confidence": 0.74
    }
  },
  "accounts": [
    {
      "cnpj": "00000000000000",
      "legal_name": "SOFTWARE EXEMPLO LTDA",
      "uf": "SP",
      "municipality_ibge": "3550308",
      "cnae_primary": "6201500"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Paginação

Se has_more for true, use next_cursor na próxima requisição. Veja Paginação com cursor.

Erros

401/403: autenticação.
422: spec inválido ou query ampla.
429: rate limit.
503: serviço indisponível.

Veja exemplos em Erros e códigos.

Notas

A lista de campos varia por plano.
filters.industry.secondary_cnae_mode:
- No caminho interativo (/v1/accounts/search), use off.
- Valores fallback e full devem ser usados no fluxo de export (/v1/exports).
Consulte GET /v1/status (ver Status) para field_allowlist e allowed_sort_fields.