Skip to content
/
Salvar filtro de prospecç...

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