Correspondência de assinantes [Beta]

O recurso “Subscriber Match” compara os dados do usuário final associados a um número de telefone com aqueles registrados na operadora de rede móvel e em fontes de dados de terceiros confiáveis. As informações podem incluir o nome do usuário, endereço, CEP, número de telefone e data de nascimento, e o Subscriber Match retornará uma resposta de correspondência para cada atributo fornecido — nenhuma informação de identificação pessoal (PII) é retornada. Esse recurso pode ser combinado com todos os outros perspectivas disponível na API.

O Subscriber Match permite que você:

  • Verify usuários reais com mais rapidez, reduzindo a rotatividade e melhorando a experiência do cliente
  • Aumentar a taxa de conversão de cadastros de clientes
  • Reduza o risco de roubo de identidade e de fraude por identidade sintética na sua empresa
  • Conheça melhor seu cliente (KYC) para cumprir as regulamentações do seu mercado
  • Combine perfeitamente o Subscriber Match com outros recursos do Insights, como a troca de SIM ou a verificação de localização, para identificar riscos e proteger as transações on-line

Observação: o uso dessa informação em ambiente de produção requer a aprovação das operadoras de telefonia móvel, que é gerenciada por meio do “Registro de Rede”. Para saber como solicitar acesso, siga este guia.

Pré-requisitos

Para usar o Identity Insights, você deve verificar se sua conta está configurada corretamente; consulte o Introdução guia para obter mais informações sobre:

  • Criando seu account,
  • Criação de uma aplicação da Vonage para uso com a API do Identity Insights,
  • Os diferentes ambientes disponíveis e como configurar sua Account para utilizá-los,
  • E como usar a interface de usuário “Introdução” do Painel de Controle para utilizar a API sem precisar escrever nenhum código.

Este guia explicará como utilizar o Subscriber Match Insight programaticamente por meio do cURL.

A API do Identity Insights está disponível por meio de vários endpoints regionais. Os exemplos deste guia utilizam o endpoint da UE, mas você pode encontrar a lista completa em Detalhes técnicos.

Fazendo uma chamada de API

A autenticação na API do Identity Insights é feita por meio de JWTs, um token JSON compacto e autônomo. Para gerar um JWT, você pode usar nosso gerador online, ou, se preferir, use o CLI da Vonage. Você precisará do ID do seu aplicativo e da chave privada para gerar o JWT. Assim que tiver o JWT, poderá enviar uma solicitação à API.

Este exemplo mostra uma solicitação cURL para o relatório de correspondência de assinantes, a fim de comparar os campos contidos no subscriber_match; você pode incluir tantos ou tão poucos atributos na matriz quanto for necessário:

curl -X POST https://api-eu.vonage.com/identity-insights/v1/requests  \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "3932462384260",
    "purpose": "FraudPreventionAndDetection",
    "insights": {
        "subscriber_match": {
            "id_document": "66666666q",
            "given_name": "Federica",
            "family_name": "Sanchez Arjona",
            "street_name": "Crawfords Corner Road",
            "street_number": "4",
            "postal_code": "07733",
            "locality": "Holmdel",
            "region": "Monmouth County",
            "country": "US",
            "house_number_extension": "Suite 2416",
            "birthdate": "1978-08-22"
          }
        }
    }'

A API comparará, então, as informações associadas a esse usuário específico de celular com as que constam nos registros da própria operadora do usuário e retornará um valor de correspondência para cada atributo fornecido:

{
  "request_id": "c2cc7a65-9b10-493f-9c0a-1c86751a91c4",
  "insights": {
    "subscriber_match": {
        "id_document_match": "EXACT",
        "given_name_match": "DATA_UNAVAILABLE",
        "family_name_match": "DATA_UNAVAILABLE",
        "address_match": "EXACT",
        "street_name_match": "EXACT",
        "street_number_match": "EXACT",
        "postal_code_match": "EXACT",
        "country_match": "EXACT",
        "birthdate_match": "NONE",
        "status": {
            "code": "OK",
            "message": "Success"
      }
    }
  }
}

Aqui, o status O objeto indica o status das informações retornadas para o número de telefone especificado:

Campo Descrição
status.code Código que indica o status da solicitação. Deve ser um dos seguintes:

NO_COVERAGE: O país ou a rede de celular não é compatível com os fornecedores disponíveis.
INVALID_PURPOSE: A finalidade indicada não é válida nem permitida para este Insight.
UNAUTHORIZED: Não foi possível autorizar a solicitação para essa combinação de aplicativo, fornecedor e número de telefone.
INTERNAL_ERROR: Ocorreu um erro interno durante o processamento da solicitação.
SUPPLIER_ERROR: O fornecedor apresentou um erro durante o processamento da solicitação.
NOT_FOUND: Não foi possível encontrar o número de telefone para este Insight.
UNSUPPORTED_NETWORK_TYPE: Esse tipo de rede não é compatível com este Insight.
INVALID_NUMBER_FORMAT: O formato do número de telefone não é válido para atribuição pelas operadoras aos usuários.
SUBSCRIBER_MATCH.ID_DOCUMENT_REQUIRED: O operador exige que o idDocument corresponda a qualquer outro atributo.
SUBSCRIBER_MATCH.ID_DOCUMENT_MISMATCH: O operador não pode ser associado ao idDocument, que é obrigatório para a correspondência com quaisquer outros atributos.
SUBSCRIBER_MATCH.INVALID_PARAM_COMBINATION: A combinação de parâmetros indicada é inválida.
OK: A informação foi processada com sucesso.
status.message Descrição mais detalhada do status.
Campo Descrição Obrigatório
id_document_match Indica se o número de identificação associado ao documento de identidade do cliente corresponde ao registrado no sistema da operadora. Não
given_name_match Indica se o nome próprio do cliente corresponde ao registrado no sistema da operadora. Não
family_name_match Indica se o sobrenome do cliente corresponde ao registrado no sistema da operadora. Não
address_match Indica se o endereço completo do cliente corresponde ao registrado no sistema da operadora. Não
street_name_match Indica se o nome da rua do cliente corresponde ao que consta no sistema da operadora. Não
street_number_match Indica se o número da rua do cliente corresponde ao registrado no sistema da operadora. Não
postal_code_match Indica se o código postal do cliente corresponde ao registrado no sistema da operadora. Não
locality_match Indica se a localidade do endereço do cliente corresponde à que consta no sistema da operadora. Não
region_match Indica se a região ou prefeitura do cliente corresponde à registrada no sistema da operadora. Não
country_match Indica se o país do endereço do cliente corresponde ao registrado no sistema da operadora. Não
house_number_extension_match Indica se o número do imóvel constante no endereço do cliente corresponde ao registrado no sistema da operadora. Não
birthdate_match Indica se a data de nascimento do cliente corresponde à que consta no sistema da operadora. Não

Cada um desses campos terá um dos seguintes valores:

  • EXACT - o valor fornecido corresponde exatamente.
  • HIGH - o valor fornecido é uma correspondência próxima, mas imperfeita.
  • PARTIAL - o valor fornecido corresponde parcialmente.
  • LOW- o valor fornecido corresponde apenas ligeiramente.
  • NONE - o valor fornecido não corresponde de forma alguma.
  • DATA_UNAVAILABLE - não há dados registrados para o atributo da solicitação.
  • INCLUDED_WITH_ADDRESS_MATCH - o valor inserido no campo de entrada foi levado em consideração no cálculo do address_match campo de resposta, mas isso ainda não foi avaliado de forma independente.

Leitura complementar