Skip to content
/
Listar filtros salvos de...

Data Stone API (1.0)

A API da Data Stone fornece acesso a dados enriquecidos de pessoas fĆ­sicas e jurĆ­dicas do Brasil.

Funcionalidades principais:

  • Consulta de informaƧƵes de pessoas e empresas
  • ProspecĆ§Ć£o e busca avanƧada com filtros personalizados
  • Enriquecimento de dados B2B em lote
  • Dados auxiliares (CNAE, CBO, geolocalizaĆ§Ć£o)
  • ValidaĆ§Ć£o de contatos WhatsApp

AutenticaĆ§Ć£o: Todas as requisiƧƵes requerem uma API Key no header Authorization.

Base URL: https://api.datastone.com.br/v1

Webhooks

Sistema de notificaĆ§Ć£o automĆ”tica via POST ao final de processos de enriquecimento ou prospecĆ§Ć£o.

  • Cadastro: Via perfil do administrador com teste automĆ”tico de disponibilidade da URL
  • MĆ©todo: POST (enviado pela API para o cliente)
  • Retry Policy: 3 tentativas com intervalo de 1 minuto entre cada
  • Timeout: 30 segundos por requisiĆ§Ć£o
  • Resposta requerida: HTTP 200 imediato

Payload do Webhook:

{
  "job_id": 123,
  "job_type": "enrichment",
  "status": "done"
}

Valores possĆ­veis para job_type: enrichment, prospecting

Valores possĆ­veis para status: requested, done, error

Rate Limiting

Limite PadrĆ£o: 100 requisiƧƵes por dia (compartilhado entre API e painel)

  • PersonalizaĆ§Ć£o: Limites podem ser customizados por conta/empresa
  • Whitelist de IPs: Administradores podem adicionar IPs que ficam isentos do rate limit
  • Resposta quando excedido: Status Code 429 Too Many Requests com bloqueio de 24 horas

Limite de Produto

Controle de uso por tipo de produto (gerenciado por administradores):

  • B2C (Consulta, Enriquecimento, ProspecĆ§Ć£o): 100.000 requisiƧƵes/mĆŖs
  • B2B (ProspecĆ§Ć£o B2B, Consulta B2B): 50.000 requisiƧƵes/mĆŖs

Resposta quando excedido: Status Code 429 Too Many Requests atĆ© inĆ­cio do prĆ³ximo perĆ­odo

Download OpenAPI description
api.json
api.yaml
Languages
Servers
Mock server
https://docs.datastone.com.br/_mock/api/
Servidor de ProduĆ§Ć£o
https://api.datastone.com.br/v1/

Consulta

OperaƧƵes de consulta direta para pessoas fĆ­sicas (CPF), empresas (CNPJ), validaĆ§Ć£o de WhatsApp e verificaĆ§Ć£o de saldo.

Operations

ProspecĆ§Ć£o B2B

OperaƧƵes de prospecĆ§Ć£o e enriquecimento B2B para pessoas e empresas, incluindo filtros avanƧados, busca com autocomplete e enriquecimento em lote.

Operations

Enriquecimento

OperaƧƵes de enriquecimento de dados em lote com layouts personalizƔveis e processamento assƭncrono.

Operations

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

2. Modo ProspecĆ§Ć£o (export: true)

  • Cria job de prospecĆ§Ć£o com filtros especificados
  • Retorna job ID
Security
ApiKeyAuth
Bodyapplication/jsonrequired
exportbooleanrequired

false = contagem apenas, true = iniciar prospecĆ§Ć£o

Example: false
namestring

Nome da pessoa (aceita busca parcial)

Example: "MARIA"
citiesArray of strings

Cidades (formato "Cidade - UF")

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

Estados (sigla UF)

Example: ["SP"]
neighborhoodsArray of strings

Bairros

Example: ["Centro","Jardins"]
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 (apenas quando export=true)

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"
    ],
    "neighborhoods": [
      "Centro",
      "Jardins"
    ],
    "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)

totalinteger
Example: 1500
Response
application/json
{
  "job_id": 12345,
  "status": "requested"
}

ProspecĆ§Ć£o de empresas (contagem e job)

Request

Duas funcionalidades em um endpoint:

1. Modo Contagem (export: false)

  • Retorna quantidade total de registros (empresas e sĆ³cios) que correspondem aos filtros
  • NĆ£o consome crĆ©ditos

2. Modo ProspecĆ§Ć£o (export: true)

  • Inicia processo de coleta de informaƧƵes detalhadas das empresas
  • Inclui dados de contato dos sĆ³cios
  • Retorna job ID
Security
ApiKeyAuth
Bodyapplication/jsonrequired
exportbooleanrequired

false = contagem apenas, true = iniciar prospecĆ§Ć£o

Example: false
namestring

RazĆ£o social ou nome fantasia (busca parcial)

Example: "TECNOLOGIA"
citiesArray of strings

Cidades (formato "Cidade - UF")

Example: ["Rio de Janeiro - RJ"]
statesArray of strings

Estados (sigla UF)

Example: ["RJ"]
cnae_codesArray of strings

CĆ³digos CNAE

Example: ["5231101","6201500"]
headquarter_typestring

Tipo de sede: H=Matriz, B=Filial

Enum"H""B"
Example: "H"
estimated_employeesArray of objects

Array de faixas de nĆŗmero estimado de funcionĆ”rios

Example: [{"upper":9},{"lower":10,"upper":49},{"lower":100},{"lower":"1","upper":"800"}]
estimated_createdArray of objects

Array de perĆ­odos de data de fundaĆ§Ć£o

Example: [{"lower":"2023-11-18","upper":"2024-11-18"},{"upper":"2020-11-18"}]
revenuesArray of objects

Array de faixas de receita anual

Example: [{"lower":"10000.00","upper":"500000.00"}]
company_typeArray of strings

Porte da empresa

Items Enum"ME""EPP""DEMAIS"
Example: ["ME","EPP"]
nature_codesArray of strings

CĆ³digos de natureza jurĆ­dica

Example: ["3999","1112","1104","1120"]
mei_typestring

Filtrar MEI

Enum"SIM""NAO"
Example: "NAO"
sector_codesArray of strings

Setores de atividade econƓmica

Example: ["ATIVIDADE FINANCEIRA SEGUROS","COMƉRCIO","INDUSTRIA"]
simple_typestring

Empresa optante pelo Simples Nacional

Enum"SIM""NAO"
Example: "SIM"
capitalsArray of objects

Array de faixas de capital social

Example: [{"lower":"5000.00","upper":"5000000.00"}]
import_exportstring

Tipo de operaĆ§Ć£o de comĆ©rcio exterior

Enum"IMPORTA""EXPORTA"
Example: "IMPORTA"
vehiclesArray of objects

Array de faixas de nĆŗmero de veĆ­culos

Example: [{"lower":"1","upper":"50"}]
quantityinteger>= 1

Quantidade de registros a exportar (apenas quando export=true)

Example: 500
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/company/prospect \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "export": false,
    "name": "TECNOLOGIA",
    "cities": [
      "Rio de Janeiro - RJ"
    ],
    "states": [
      "RJ"
    ],
    "cnae_codes": [
      "5231101",
      "6201500"
    ],
    "headquarter_type": "H",
    "estimated_employees": [
      {
        "upper": 9
      },
      {
        "lower": 10,
        "upper": 49
      },
      {
        "lower": 100
      },
      {
        "lower": "1",
        "upper": "800"
      }
    ],
    "estimated_created": [
      {
        "lower": "2023-11-18",
        "upper": "2024-11-18"
      },
      {
        "upper": "2020-11-18"
      }
    ],
    "revenues": [
      {
        "lower": "10000.00",
        "upper": "500000.00"
      }
    ],
    "company_type": [
      "ME",
      "EPP"
    ],
    "nature_codes": [
      "3999",
      "1112",
      "1104",
      "1120"
    ],
    "mei_type": "NAO",
    "sector_codes": [
      "ATIVIDADE FINANCEIRA SEGUROS",
      "COMƉRCIO",
      "INDUSTRIA"
    ],
    "simple_type": "SIM",
    "capitals": [
      {
        "lower": "5000.00",
        "upper": "5000000.00"
      }
    ],
    "import_export": "IMPORTA",
    "vehicles": [
      {
        "lower": "1",
        "upper": "50"
      }
    ],
    "quantity": 500,
    "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)

total_companiesinteger
Example: 850
total_partnersinteger
Example: 2100
Response
application/json
{
  "job_id": 54321,
  "status": "requested"
}

Obter resultado da prospecĆ§Ć£o

Request

Recupera o resultado de um job de prospecĆ§Ć£o.

Se webhook foi configurado, o status do processo serĆ” enviado automaticamente.

Security
ApiKeyAuth
Path
job_idintegerrequired

ID do job de prospecĆ§Ć£o

Example: 12345
curl -i -X GET \
  https://docs.datastone.com.br/_mock/api/prospection/12345/result \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Resultado retornado com sucesso

Bodyapplication/json
job_idinteger
Example: 12345
statusstring
Enum"requested""done""error"
Example: "done"
resultobject

Dados prospectados

Response
application/json
{
  "job_id": 12345,
  "status": "done",
  "result": {}
}

Salvar filtro de prospecĆ§Ć£o

Request

Salva um conjunto de filtros para reutilizaĆ§Ć£o posterior.

Permite armazenar filtros complexos de pessoas ou empresas para uso recorrente.

Security
ApiKeyAuth
Bodyapplication/jsonrequired
filter_namestringrequired

Nome do filtro

Example: "Executivos SP"
filter_typeintegerrequired

Tipo de filtro (1=pessoas, 2=empresas)

Enum12
Example: 1
dataobjectrequired

Objeto contendo os filtros (mesma estrutura usada em /persons/prospect ou /company/prospect)

Example: {"cities":["SĆ£o Paulo - SP"],"professions":["999999"],"age":{"min_age":30,"max_age":50}}
curl -i -X POST \
  https://docs.datastone.com.br/_mock/api/prospection/filters \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "filter_name": "Executivos SP",
    "filter_type": 1,
    "data": {
      "cities": [
        "SĆ£o Paulo - SP"
      ],
      "professions": [
        "999999"
      ],
      "age": {
        "min_age": 30,
        "max_age": 50
      }
    }
  }'

Responses

Filtro salvo com sucesso

Bodyapplication/json
filter_idinteger
Example: 123
messagestring
Example: "Filtro salvo com sucesso"
Response
application/json
{
  "filter_id": 123,
  "message": "Filtro salvo com sucesso"
}

Listar filtros salvos de pessoas

Request

Recupera todos os filtros salvos para prospecĆ§Ć£o de pessoas

Security
ApiKeyAuth
curl -i -X GET \
  https://docs.datastone.com.br/_mock/api/prospection/filters/list_person \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Filtros retornados com sucesso

Bodyapplication/jsonArray [
filter_idinteger
Example: 123
filter_namestring
Example: "Executivos SP"
dataobject

Filtros salvos

created_atstring(date-time)
Example: "2023-01-15T10:30:00Z"
]
Response
application/json
[
  {
    "filter_id": 123,
    "filter_name": "Executivos SP",
    "data": {},
    "created_at": "2023-01-15T10:30:00Z"
  }
]

Listar filtros salvos de empresas

Request

Recupera todos os filtros salvos para prospecĆ§Ć£o de empresas

Security
ApiKeyAuth
curl -i -X GET \
  https://docs.datastone.com.br/_mock/api/prospection/filters/list_company \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Filtros retornados com sucesso

Bodyapplication/jsonArray [
filter_idinteger
Example: 456
filter_namestring
Example: "Empresas Tech RJ"
dataobject

Filtros salvos

created_atstring(date-time)
Example: "2023-01-15T10:30:00Z"
]
Response
application/json
[
  {
    "filter_id": 456,
    "filter_name": "Empresas Tech RJ",
    "data": {},
    "created_at": "2023-01-15T10:30:00Z"
  }
]

Auxiliares

Dados auxiliares como CNAE, CBO, geolocalizaĆ§Ć£o (estados, cidades, bairros) e setores empresariais.

Operations