Recuperação dos dados do titular do CNAM

A partir de 4 de fevereiro de 2027, a Vonage encerrará o serviço Vonage Number Insights. Para garantir um suporte ininterrupto e oferecer uma solução mais escalável e preparada para o futuro, recomendamos que você migre para nossa oferta aprimorada: API do Vonage Identity Insights. A Number Insight API consolida vários conjuntos de dados relacionados a números de telefone em uma única API flexível, permitindo que você solicite informações em tempo real sobre um número de telefone e obtenha qualquer combinação de informações — como formatação do número, detalhes da operadora, troca de SIM e correspondência de assinante — em uma única chamada.

Por favor, verifique o Guia de Transição do Numbers Insights, que oferece orientações detalhadas sobre as diferenças nas APIs, as alterações necessárias e as melhores práticas para uma transição tranquila.

Visão geral

A Number Insight API da Vonage permite que você obtenha os dados do titular (CNAM) de diversos números de telefone nos Estados Unidos. Isso inclui números de telefone fixo e celular, tanto de pessoas físicas quanto de empresas.

CNAM é uma sigla que significa “Caller ID Name” (Nome do chamador). As redes dos EUA utilizam esse recurso para exibir o nome do chamador junto com o número de telefone, a fim de ajudar os usuários a identificar quem está ligando.

A Number Insight API fornece apenas detalhes de CNAM para números dos EUA: ela não pode retornar essas informações para números de outros países.

Como fazer a solicitação

Passagem cnam=true quando usado como parâmetro adicional em uma chamada à API Avançada, ele consulta o CNAM desse número.

O exemplo a seguir mostra como se pode solicitar dados CNAM usando curl:

curl "https://api.nexmo.com/ni/advanced/json?api_key=VONAGE_API_KEY&api_secret=VONAGE_API_SECRET&number=14155550100&cnam=true"

Compreendendo a resposta

Na resposta retornada pela Number Insight API, os seguintes campos estão relacionados ao CNAM:

  • caller_name: o nome do proprietário
  • caller_type: ou business ou consumer dependendo do tipo de número
  • first_name e last_name: apenas para números de consumidores

Exemplo de consumidor

{
    "status": 0,
    "status_message": "Success",
    "lookup_outcome": 1,
    "lookup_outcome_message": "Partial success - some fields populated",
    "request_id": "50793c0c-8025-408f-ab9a-71cbbaf033bf",
    "international_format_number": "14155550100",
    "national_format_number": "(415) 55500100",
    "country_code": "US",
    "country_code_iso3": "USA",
    "country_name": "United States of America",
    "country_prefix": "1",
    "request_price": "0.04000000",
    "remaining_balance": "10.000000",
    "current_carrier": {
        "network_code": "310004",
        "name": "Verizon Wireless",
        "country": "US",
        "network_type": "mobile"
    },
    "original_carrier": {
        "network_code": "310004",
        "name": "Verizon Wireless",
        "country": "US",
        "network_type": "mobile"
    },
    "valid_number": "valid",
    "reachable": "unknown",
    "ported": "not_ported",
    "roaming": {"status": "unknown"},
    "ip_warnings": "unknown",
    "caller_name": "Wile E. Coyote",
    "last_name": "Coyote",
    "first_name": "Wile",
    "caller_type": "consumer"
}

Exemplo de negócio

{
    "status": 0,
    "status_message": "Success",
    "lookup_outcome": 1,
    "lookup_outcome_message": "Partial success - some fields populated",
    "request_id": "27c61a46-5b4a-4e80-b16d-725432559078",
    "international_format_number": "14155550101",
    "national_format_number": "(415) 555-0101",
    "country_code": "US",
    "country_code_iso3": "USA",
    "country_name": "United States of America",
    "country_prefix": "1",
    "request_price": "0.04000000",
    "remaining_balance": "10.000000",
    "current_carrier": {
        "network_code": "US-FIXED",
        "name": "United States of America Landline",
        "country": "US",
        "network_type": "landline"
    },
    "original_carrier": {
        "network_code": "US-FIXED",
        "name": "United States of America Landline",
        "country": "US",
        "network_type": "landline"
    },
    "valid_number": "valid",
    "reachable": "unknown",
    "ported": "not_ported",
    "roaming": {"status": "unknown"},
    "ip_warnings": "unknown",
    "caller_name": "ACME Corporation",
    "caller_type": "business"
}