Subscriber Match

The Subscriber Match insight compares end-user data for a phone number with that on file with their mobile network operator. The information can include the user's name, address, postal code, phone number, and birth date, and Subscriber Match will return a match response for each given attribute - no Personal Identifiable Information (PII) is returned. This insight can be combined with all other insights available in the API.

Subscriber Match allows you to:

  • Verify real users more quickly, reducing churn and improving the customer experience
  • Increase the conversion rate of customer signups
  • Reduce the risk of identity theft and synthetic identity fraud on your business
  • Know Your Customer (KYC) better to comply with regulations in your market
  • Seamlessly combine Subscriber Match with other Insights, such as SIM Swap or Location Verification, to identify risk and secure online transactions

Prerequisites

To use Identity Insights, you must ensure your account is configured correctly; see the Getting Started guide for more information on:

  • Creating your account,
  • Creating a Vonage application for use with the Identity Insights API,
  • The different environments available and how to configure your account to use them,
  • And how to use the Dashboard Getting Started UI to use the API without writing any code.

This guide will explain how to use the Subscriber Match Insight programatically using cURL.

Making an API Call

Authentication for the Identity Insights API is done via JWTs, a compact and self-contained JSON token. To generate a JWT, you can use our online generator, or alternatively use the Vonage CLI. You will need your application ID and private key to generate the JWT. Once you have your JWT, you can send a request to the API.

This example shows a cURL request for the subscriber match insight to compare the fields contained within the subscriber_match; you can include as many or as few attributes in the array as required:

curl -X POST https://api-eu.vonage.com/v0.1/identity-insights \
  -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"
          }
        }
    }'

The API will then compare the information associated with the particular mobile phone user with that on file (and verified) from the mobile phone user's operator's own records, and return a match value for each attribute provided:

{
  "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": "PARTIAL_SUCCESS",
            "message": "Unable to retrieve data for some fields."
      }
    }
  }
}

Each field within the subscriber_match array will have one of the following values:

  • EXACT - the value provided matches exactly.
  • HIGH - the value provided is a close but imperfect match.
  • PARTIAL - the value provided partially matches.
  • LOW- the value provided matches only slightly.
  • NONE - the value provided does not match at all.
  • DATA_UNAVAILABLE - there is no data held for the request attribute.

Additionally, there is a status array showing the outcome of the request:

  • code - will be one of the following values:
    • UNAUTHORIZED - there's an issue with the authentication for the request.
    • INVALID_PURPOSE - the purpose provided in the request is not valid.
    • INVALID_NUMBER_FORMAT - the format of the phone number is invalid.
    • NOT_FOUND - the provided phone number cannot be found by the operator.
    • NO_COVERAGE - there is no coverage for the API in the country the user is in.
    • INTERNAL_ERROR- the API has returned an error.
    • SUPPLIER_ERROR - there is an issue with one of the provided attributes. More detailed information will be given in the message field.
    • PARTIAL_SUCCESS - one or more attributes has returned DATA_UNAVAILABLE.
    • OK - all attributes have returned a match response.
    • SUBSCRIBER_MATCH.ID_DOCUMENT_REQUIRED - operator requires idDocument to match any other attributes.
    • SUBSCRIBER_MATCH.ID_DOCUMENT_MISMATCH - operator cannot match idDocument which is required to match any other attributes.
    • SUBSCRIBER_MATCH.INVALID_PARAM_COMBINATION - indicated parameter combination is invalid.
  • message - contains a more detailed status description.

Further Reading