Using Multiple Insights

When using the Identity Insights API, users can retrieve any combination of different datasets, known as insights, in a single API call.

For example, this cURL request will return both the SIM Swap and Subscriber Match insights:

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": {
        "sim_swap": {
         "period": 240
          },
        "subscriber_match": {
            "id_document": "66666666q",
            "name": "Federica Sanchez Arjona",
            "given_name": "Federica",
            "family_name": "Sanchez Arjona",
            "address": "101 Crawfords Corner Road Ste 2416",
            "street_name": "Crawfords Corner Road",
            "street_number": "101",
            "postal_code": "07733",
            "country": "US",
            "house_number_extension": "Suite 2416",
            "birthdate": "1978-08-22",
            }
        }
    }'

The response will then contain the results of both insight requests in the insights object:

{
   "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "insights": {
    "sim_swap": {
        "latest_sim_swap_at": "2024-07-08T09:30:27.504Z",
        "is_swapped": true,
        "status": {
          "code": "NO_COVERAGE",
          "message": "Success"
        }
    },
  "subscriber_match": {
    "id_document_match": "EXACT",
    "name_match": "HIGH",
    "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."
      }
    }
  }
}

Similarly, this API call will return the Format, Current Carrier, and Location Verification insights:

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": {
        "format": {},
        "current_carrier": {},
        "location_verification": {
         "location": {
            "type": "CIRCLE",
            "radius": 3000,
            "center": {
               "latitude": -90,
               "longitude": -180
                }
            }
          }
        }
    }'

The response will then contain the results of all insights in the insights object:

{
    "request_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
    "insights": {
        "format": {
            "country_code": "US",
            "country_name": "United States",
            "country_prefix": "1",
            "offline_location": "Georgia",
            "time_zones": [
            "America/New_York"
            ],
            "number_international": "+14040000000",
            "number_national": "(404) 000-0000",
            "is_format_valid": true,
            "status": {
            "code": "NO_COVERAGE",
            "message": "Success"
            }
        },
        "current_carrier": {
            "name": "Orange Espana, S.A. Unipersonal",
            "network_type": "MOBILE",
            "country_code": "ES",
            "network_code": "21403",
            "status": {
            "code": "NO_COVERAGE",
            "message": "Success"
            }
        },
        "location_verification": {
            "is_verified": "TRUE",
            "latest_location_at": "2024-07-08T09:30:27.504Z",
            "match_rate": 1,
            "status": {
            "code": "NO_COVERAGE",
            "message": "Success"
            }
        }
    }
}