Skip to content
/
Consultar saldo da conta

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

Consultar saldo da conta

Request

Retorna informações de saldo e créditos disponíveis na conta por produto

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

Responses

Saldo retornado com sucesso

Bodyapplication/json
balanceobject
is_posboolean

Indica se a conta é pós-paga

Example: false
Response
application/json
{
  "balance": {
    "wallet": { … },
    "credits": [ … ]
  },
  "is_pos": false
}

Consultar informações de pessoas físicas

Request

Busca informações detalhadas de pessoa física por CPF

Security
ApiKeyAuth
Query
cpfstring^\d{11}$required

CPF da pessoa (apenas números)

Example: cpf=12345678901
fieldsstring

Campos específicos a retornar (separados por vírgula)

Example: fields=name,cpf,emails,addresses
curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/persons?cpf=12345678901&fields=name%2Ccpf%2Cemails%2Caddresses' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Informações da pessoa retornadas com sucesso

Bodyapplication/jsonArray [
cpfstring
Example: "11111111111"
namestring
Example: "FULANO DE TAL EXEMPLO"
mother_namestring
Example: "MARIA EXEMPLO"
birthdaystring(date)
Example: "1993-01-01"
agestring
Example: "30"
genderstring
Enum"M""F"
Example: "M"
signstring
Example: "Capricórnio"
registry_situationstring
Example: "REGULAR"
pepboolean
Example: false
pep_typestring
Example: ""
possibly_deadboolean
Example: false
retiredboolean
Example: false
bolsa_familiaboolean
Example: false
estimated_incomestring
Example: "ATÉ R$ 1.000,00"
cbo_codestring
Example: "999999"
cbo_descriptionstring
Example: "EMPRESÁRIO"
rgstring or null
addressesArray of objects
emailsArray of objects
mobile_phonesArray of objects
land_linesArray of objects
family_personsArray of objects
related_companiesArray of objects
employerArray of objects
ipstring
Example: "127.0.0.1"
planstring
Example: "Consulta Premium"
]
Response
application/json
[
  {
    "cpf": "11111111111",
    "name": "FULANO DE TAL EXEMPLO",
    "mother_name": "MARIA EXEMPLO",
    "birthday": "1993-01-01",
    "age": "30",
    "gender": "M",
    "sign": "Capricórnio",
    "registry_situation": "REGULAR",
    "pep": false,
    "pep_type": "",
    "possibly_dead": false,
    "retired": false,
    "bolsa_familia": false,
    "estimated_income": "ATÉ R$ 1.000,00",
    "cbo_code": "999999",
    "cbo_description": "EMPRESÁRIO",
    "rg": "string",
    "addresses": [ … ],
    "emails": [ … ],
    "mobile_phones": [ … ],
    "land_lines": [ … ],
    "family_persons": [ … ],
    "related_companies": [ … ],
    "employer": [ … ],
    "ip": "127.0.0.1",
    "plan": "Consulta Premium"
  }
]

Consultar informações de empresas

Request

Busca informações detalhadas de empresa por CNPJ

Security
ApiKeyAuth
Query
cnpjstring^\d{14}$required

CNPJ da empresa (apenas números)

Example: cnpj=12345678000199
fieldsstring

Campos específicos a retornar (separados por vírgula)

Example: fields=company_name,cnpj,emails,partners
curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/companies?cnpj=12345678000199&fields=company_name%2Ccnpj%2Cemails%2Cpartners' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Informações da empresa retornadas com sucesso

Bodyapplication/jsonArray [
cnpjstring
Example: "12345678000199"
company_namestring
Example: "FULANO DE TAL EXEMPLO"
trading_namestring
Example: "EMPRESA EXEMPLO"
creation_datestring(date)
Example: "2022-01-01"
agestring
Example: "3 anos 3 meses"
business_sizestring
Example: "ME"
city_ufstring
Example: "CIDADE EXEMPLO, EX"
cnae_codeinteger
Example: 9511800
cnae_descriptionstring
Example: "Reparação e manutenção de computadores e de equipamentos periféricos"
registry_situationstring
Example: "ATIVA"
addressesArray of objects
branch_officesArray of objects
partnersArray of objects
emailsArray of objects
land_linesArray of objects
mobile_phonesArray of objects
]
Response
application/json
[
  {
    "cnpj": "12345678000199",
    "company_name": "FULANO DE TAL EXEMPLO",
    "trading_name": "EMPRESA EXEMPLO",
    "creation_date": "2022-01-01",
    "age": "3 anos 3 meses",
    "business_size": "ME",
    "city_uf": "CIDADE EXEMPLO, EX",
    "cnae_code": 9511800,
    "cnae_description": "Reparação e manutenção de computadores e de equipamentos periféricos",
    "registry_situation": "ATIVA",
    "addresses": [ … ],
    "branch_offices": [ … ],
    "partners": [ … ],
    "emails": [ … ],
    "land_lines": [ … ],
    "mobile_phones": [ … ]
  }
]

Buscar empresas

Request

Buscar empresas por razão social, email, domínio, CEP ou telefone.

Permite buscas sem necessidade de CNPJ.

Security
ApiKeyAuth
Query
razao_socialstring

Razão social da empresa

Example: razao_social=EMPRESA EXEMPLO LTDA
emailstring

Email da empresa

Example: email=contato@empresa.com
domainstring

Domínio do site da empresa

Example: domain=empresa.com.br
cepstring

CEP da empresa

Example: cep=01310100
phonestring

Telefone da empresa

Example: phone=1133334444
ufstring^[A-Z]{2}$

Estado (sigla UF)

Example: uf=SP
curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/company/list?razao_social=EMPRESA+EXEMPLO+LTDA&email=contato%40empresa.com&domain=empresa.com.br&cep=01310100&phone=1133334444&uf=SP' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Empresas encontradas com sucesso

Bodyapplication/jsonArray [
object

Dados da empresa (mesmo schema do /companies)

]
Response
application/json
[
  {}
]

Buscar matriz e filiais

Request

Localizar matriz e todas as filiais de uma empresa a partir de qualquer CNPJ do grupo.

Retorna informações de todas as unidades (matriz + filiais).

Security
ApiKeyAuth
Query
cnpjstring^\d{14}$required

CNPJ da empresa (matriz ou filial)

Example: cnpj=12345678000199
curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/company/search/filial?cnpj=12345678000199' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Matriz e filiais encontradas com sucesso

Bodyapplication/json
matrizobject

Dados da matriz

filiaisArray of objects

Lista de filiais

Response
application/json
{
  "matriz": {},
  "filiais": [
    {}
  ]
}

Validar status de contato WhatsApp

Request

Verifica se um número de telefone está ativo no WhatsApp.

IMPORTANTE: Os campos ddd e phone devem ser enviados separadamente, sem formatação (sem traços ou espaços).

Security
ApiKeyAuth
Query
dddstring^\d{2}$required

DDD do telefone (exatamente 2 dígitos)

Example: ddd=11
phonestring^\d{1,9}$required

Número do telefone (até 9 dígitos, apenas números)

Example: phone=987654321
curl -i -X GET \
  'https://docs.datastone.com.br/_mock/api/whatsapp/search?ddd=11&phone=987654321' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Status do WhatsApp retornado com sucesso

Bodyapplication/json
statusstring
Enum"ATIVO""INATIVO"
Example: "ATIVO"
Response
application/json
{
  "status": "ATIVO"
}

Validar múltiplos números WhatsApp

Request

Verifica o status de múltiplos números de telefone no WhatsApp em uma única requisição.

Processamento assíncrono com callback.

Limite: Até 1000 números por requisição

Security
ApiKeyAuth
Bodyapplication/jsonrequired
phonesArray of strings<= 1000 itemsrequired

Array de números completos (até 11 dígitos cada)

Example: ["11987654321","21987654321"]
callback_urlstring

URL para receber callback com resultados

Example: "https://seusite.com/callback"
curl -i -X POST \
  https://docs.datastone.com.br/_mock/api/whatsapp/batch \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "phones": [
      "11987654321",
      "21987654321"
    ],
    "callback_url": "https://seusite.com/callback"
  }'

Responses

Job de validação criado com sucesso

Bodyapplication/json
job_idinteger

ID do job de processamento

Example: 12345
statusstring
Example: "requested"
total_numbersinteger

Total de números a serem validados

Example: 100
Response
application/json
{
  "job_id": 12345,
  "status": "requested",
  "total_numbers": 100
}

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

Auxiliares

Dados auxiliares como CNAE, CBO, geolocalização (estados, cidades, bairros) e setores empresariais.

Operations