Skip to content

Prospecção

Operações de prospecção com filtros geográficos e profissionais, incluindo contagem e geração de jobs de prospecção.

Operations

Prospecção de pessoas (contagem e job)

Request

Duas funcionalidades em um endpoint:

1. Modo Contagem (export: false)

  • Retorna quantidade total de pessoas que correspondem aos filtros
  • Não consome créditos
  • Resposta: {"count": 1500}

2. Modo Prospecção (export: true)

  • Cria job de prospecção com filtros especificados
  • name e quantity passam a ser obrigatórios (name é o nome dado ao job; quantity é o volume a exportar). Faltando qualquer um dos dois a API responde the quantity, name and some location are required fields when export is True.
  • Resposta: {"id": 12345} - use esse id em /prospection/{job_id}/result/

Filtro de localização obrigatório em TODA chamada: vale também para a contagem (export=false), não só para o export. É preciso enviar pelo menos um entre cities, states, ddds, neighborhoodies ou geo_points. Sem nenhum deles a API responde You must select at least one locale filter.

Atenção ao geo_points: ele satisfaz essa exigência, mas não é aplicado ao resultado neste endpoint (ver a descrição do campo). Usá-lo sozinho retorna/exporta a base sem recorte geográfico — prefira cities, states, ddds ou neighborhoodies.

Security
ApiKeyAuth
Bodyapplication/jsonrequired
exportbooleanrequired

false = contagem apenas, true = iniciar prospecção

Example:false
namestring

Nome da pessoa (aceita busca parcial). Obrigatório quando export=true (junto com quantity), pois é usado como nome do job de prospecção; opcional em export=false.

Example:"MARIA"
citiesArray of strings

Cidades (formato "Cidade - UF")

Example:
[
  "São Paulo - SP"
]
statesArray of strings

Estados (sigla UF)

Example:
[
  "SP"
]
dddsArray of strings

DDDs de telefone (2 dígitos)

Example:
[
  "11",
  "21"
]
neighborhoodiesArray of strings

Bairros, no formato "BAIRRO - CIDADE - UF" (três partes separadas por -). Fora desse formato a API responde The format sent is not valid.. Ex.: CENTRO - SÃO PAULO - SP.

O nome do parâmetro tem mesmo esse typo (neighborhoodies) - é o que a API aceita e o que ela enumera na mensagem de erro dos filtros de localização. neighborhoods não é reconhecido.

Inconsistência conhecida: a exclusão de bairros usa a grafia correta (exclude_neighborhoods), enquanto a inclusão usa neighborhoodies.

Example:
[
  "CENTRO - SÃO PAULO - SP",
  "JARDINS - SÃO PAULO - SP"
]
geo_pointsobject

Recorte geográfico. É um objeto único (não um array), com type e data. Três formas são aceitas:

  • circle — {"type": "circle", "data": {"radius": 5000, "center": {"lat": -23.5, "lng": -46.6}}} (radius em metros)
  • rectangle — {"type": "rectangle", "data": {"north": -23.4, "south": -23.7, "east": -46.5, "west": -46.8}}
  • polygon — {"type": "polygon", "data": [{"lat": -23.5, "lng": -46.6}, {"lat": -23.6, "lng": -46.7}]}

A longitude é lng (não lon).

AVISO: atualmente geo_points satisfaz a exigência de filtro de localização mas NÃO é aplicado ao resultado nos endpoints de prospecção. Enviá-lo sozinho faz a contagem/exportação rodar sem nenhum recorte geográfico (ou seja, sobre a base inteira). Até que isso seja corrigido, use cities, states, ddds ou neighborhoodies.

Example:
{
  "type": "circle",
  "data": {
    "radius": 5000,
    "center": { … }
  }
}
cbo_codesArray of strings

Códigos CBO de profissões

Example:
[
  "252105",
  "212305"
]
genderstring

Gênero (M=Masculino, F=Feminino)

Enum:"M""F"
Example:"M"
estimated_incomeArray of objects

Faixas de renda estimada

Example:
[
  {
    "lower": "1000.00",
    "upper": "500000.00"
  }
]
birthdayobject

Período de data de nascimento

ageobject

Faixa etária

contact_channelsArray of strings

Canais de contato disponíveis

Items Enum:"whatsapp""sms""phone""email""address"
Example:
[
  "email",
  "whatsapp"
]
match_profileArray of strings

Códigos dos perfis predefinidos - usar campo "code" do endpoint /persons/prospect/profile

Example:
[
  "PF1"
]
quantityinteger, >= 1

Quantidade de registros a exportar. Obrigatório quando export=true (junto com name); ignorado em export=false.

Example:1000
callback_emailstring, (email)

Email para notificação quando job concluir (apenas quando export=true)

Example:"usuario@empresa.com"
planstring

Plano de extração (sempre "3" para export=true)

Value:"3"
Example:"3"
file_formattingstring

Formato do arquivo de exportação (apenas quando export=true)

Enum:"excel""csv"
Example:"excel"
curl -i -X POST \
  https://docs.datastone.com.br/_mock/api/persons/prospect/ \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "export": false,
    "name": "MARIA",
    "cities": [
      "São Paulo - SP"
    ],
    "states": [
      "SP"
    ],
    "ddds": [
      "11",
      "21"
    ],
    "neighborhoodies": [
      "CENTRO - SÃO PAULO - SP",
      "JARDINS - SÃO PAULO - SP"
    ],
    "geo_points": {
      "type": "circle",
      "data": {
        "radius": 5000,
        "center": {
          "lat": -23.5,
          "lng": -46.6
        }
      }
    },
    "cbo_codes": [
      "252105",
      "212305"
    ],
    "gender": "M",
    "estimated_income": [
      {
        "lower": "1000.00",
        "upper": "500000.00"
      }
    ],
    "birthday": {
      "start_date": "1980-01-01",
      "end_date": "1990-12-31"
    },
    "age": {
      "lower": "18",
      "upper": "90"
    },
    "contact_channels": [
      "email",
      "whatsapp"
    ],
    "match_profile": [
      "PF1"
    ],
    "quantity": 1000,
    "callback_email": "usuario@empresa.com",
    "plan": "3",
    "file_formatting": "excel"
  }'

Responses

Resposta de contagem ou job criado

Bodyapplication/json
One of:

Resposta de contagem (export=false)

countinteger

Quantidade de pessoas que correspondem aos filtros. A chave é count - não existe total na resposta.

Example:1500
Response
{
  "count": 1500
}