Sign In

Consulta CPF — Telefones

Last updated

Retorna telefones vinculados ao CPF, organizados por prioridade, sem duplicidade e com indicação de WhatsApp quando disponível.

Propriedade Valor
Dataset cpf_telefones
Método e caminho POST /datasets/cpf_telefones/queries
Versão do schema de dados (schema_version) 1.0.0
Entrada CPF
Consultas em lote Suportadas, conforme disponibilidade no catálogo

Requisição

curl --request POST 'https://api.verifica-online.com.br/datasets/cpf_telefones/queries' \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: exemplo-cpf-telefones-001' \
  --data '{"cpf":"52998224725"}'
{
  "cpf": "52998224725"
}
Campo Tipo Obrigatório Regras
cpf string Sim Exatamente 11 dígitos, sem pontuação ou espaços, com dígitos verificadores válidos. Sequências de um único dígito repetido são rejeitadas.

O corpo aceita somente cpf; campos adicionais e CPF numérico são rejeitados. Não são aceitos parâmetros de consulta na URL. Validar os dígitos não comprova existência, identidade ou titularidade do documento.

Veja autenticação e requisições, idempotência e cobrança.

Exemplo de data

O CPF é didático; o nome de uma pessoa não é retornado por esta consulta. O telefone abaixo é sintético e não deve ser utilizado para contato. O exemplo não garante resposta, disponibilidade da linha ou titularidade. Os campos externos a data estão descritos em resultados.

{
  "cpf": "52998224725",
  "total": 1,
  "phones": [
    {
      "country_code": "55",
      "area_code": "11",
      "number": "900000000",
      "e164": "+5511900000000",
      "type": "mobile",
      "priority": 1,
      "has_whatsapp": null
    }
  ]
}

Contrato de data

data é um objeto ou null. Quando há dados, todas as propriedades abaixo estão presentes e não há propriedades adicionais.

Campo Tipo Descrição e limites
cpf string CPF consultado, com 11 dígitos sem pontuação.
total integer Quantidade de telefones retornados após seleção e remoção de duplicidades; igual a phones.length.
phones array<object> Lista de até 1.000 telefones. Em um resultado com dados, contém pelo menos um item.
phones[].country_code string Código de discagem internacional, com um a três dígitos, sem +.
phones[].area_code string Código de área, com dois dígitos.
phones[].number string Número local, com oito ou nove dígitos, sem máscara. Preserve zeros iniciais.
phones[].e164 string Representação formada por +, código do país, código de área e número local, nessa ordem.
phones[].type string mobile para celular, landline para telefone fixo ou unknown quando a classificação não é reconhecida.
phones[].priority integer ou null Prioridade informada; pode ser negativa. null indica ausência ou valor não aproveitável.
phones[].has_whatsapp boolean ou null true ou false quando há indicação reconhecida; null significa informação desconhecida. Não comprova acesso atual a uma conta de WhatsApp.

Os componentes numéricos são retornados somente com dígitos e seguem os comprimentos indicados. A lista contém valores únicos de e164, ordenados por prioridade crescente. Ausência de prioridade é tratada como o menor nível de prioridade; a ordem entre itens de mesma prioridade não é garantida. A adequação ao formato não comprova existência, funcionamento ou titularidade da linha.

Ausência de dados e cobrança

Ausência reconhecida de telefones produz status: "no_data" e data: null, sem cobrança. Uma lista não vazia sem nenhuma entrada aproveitável, uma resposta incoerente ou acima do limite de itens resulta em erro, sem cobrança.

Em uma consulta comum com status: "succeeded", aplica-se o preço efetivo da conta. Consulte GET /datasets para disponibilidade, schema e preço vigentes, e billing para a cobrança da operação. Veja resultados e erros.

Consultas em lote

O dataset aceita POST /datasets/cpf_telefones/batches quando batch.enabled estiver habilitado no catálogo. Cada CPF usa este mesmo contrato. Veja consultas em lote para limites, validação por entrada, reserva, cobrança consolidada, recuperação e webhook.