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.
The Identity Insights API is available via multiple regional endpoints. The examples in this guide use the EU endpoint, but you can find the full list in Technical Details.
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"
}
}
}
}