# Prospecção de pessoas (contagem e job)

Duas funcionalidades em um endpoint:

1. Modo Contagem (export: false)
- Retorna quantidade total de pessoas que correspondem aos filtros
- Não consome créditos

2. Modo Prospecção (export: true)
- Cria job de prospecção com filtros especificados
- Retorna job ID

Endpoint: POST /persons/prospect
Version: 1.0
Security: ApiKeyAuth

## Request fields (application/json):

  - `export` (boolean, required)
    false = contagem apenas, true = iniciar prospecção

  - `name` (string)
    Nome da pessoa (aceita busca parcial)
    Example: "MARIA"

  - `cities` (array)
    Cidades (formato "Cidade - UF")
    Example: ["São Paulo - SP"]

  - `states` (array)
    Estados (sigla UF)
    Example: ["SP"]

  - `neighborhoods` (array)
    Bairros
    Example: ["Centro","Jardins"]

  - `cbo_codes` (array)
    Códigos CBO de profissões
    Example: ["252105","212305"]

  - `gender` (string)
    Gênero (M=Masculino, F=Feminino)
    Enum: "M", "F"

  - `estimated_income` (array)
    Faixas de renda estimada
    Example: [{"lower":"1000.00","upper":"500000.00"}]

  - `estimated_income.lower` (string)
    Valor mínimo da faixa
    Example: "1000.00"

  - `estimated_income.upper` (string)
    Valor máximo da faixa
    Example: "500000.00"

  - `birthday` (object)
    Período de data de nascimento

  - `birthday.start_date` (string)
    Example: "1980-01-01"

  - `birthday.end_date` (string)
    Example: "1990-12-31"

  - `age` (object)
    Faixa etária

  - `age.lower` (string)
    Example: "18"

  - `age.upper` (string)
    Example: "90"

  - `contact_channels` (array)
    Canais de contato disponíveis
    Enum: "whatsapp", "sms", "phone", "email", "address"

  - `match_profile` (array)
    Códigos dos perfis predefinidos - usar campo "code" do endpoint /persons/prospect/profile
    Example: ["PF1"]

  - `quantity` (integer)
    Quantidade de registros a exportar (apenas quando export=true)
    Example: 1000

  - `callback_email` (string)
    Email para notificação quando job concluir (apenas quando export=true)
    Example: "usuario@empresa.com"

  - `plan` (string)
    Plano de extração (sempre "3" para export=true)
    Enum: "3"

  - `file_formatting` (string)
    Formato do arquivo de exportação (apenas quando export=true)
    Enum: "excel", "csv"

## Response 400 fields (application/json):

  - `error` (object)

  - `error.code` (string)
    Example: "no credits"

  - `error.description` (string)
    Example: "Você não possui saldo suficiente, disponível 0"

## Response 403 fields (application/json):

  - `error` (string)
    Example: "Invalid token"