Location Verification

The Location Verification insight allows you to verify the location of an end-user device within a specified area. It uses cellular network positioning techniques to locate the device, providing several benefits over GPS positioning including:

• Secure and Trusted: Cellular network positioning uses information directly from the mobile operator networks, eliminating the risk of GPS spoofing and circumvention via VPN.
• Simplified integration: Identity Insights can easily be integrated into your applications, reducing software development complexity and effort.

Some fraud prevention use cases where the Location Verification is useful:

• Ecommerce User Verification: Ecommerce and content platforms face challenges with users consuming services, content and licenses outside the region for which they have been licensed. The Location Verification insight allows these platforms to verify if an end user's location is within the authorized region for the service, content or license.
• Point of Sale Verification: When a user is making a purchase at a store using their credit/bank card, sometimes their financial provider will want to verify if that transaction is fraudulent. Location Verification could be used with the phone number entered into their banking application to query the location where the transaction was initiated, to confirm the user is at that location.
• Location Based Content: Verify a user's location during sports events or concerts to enrich their experience with custom content, such as goal replays, different angles, useful information, and more.

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 Location Verification 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 Location Verification insight to check whether the location of certain user device is within the area specified:

curl -X POST https://api-eu.vonage.com/v0.1/identity-insights \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "14040000000",
    "purpose": "FraudPreventionAndDetection",
    "insights": {
      "location_verification": {
         "location": {
            "type": "CIRCLE",
            "radius": 3000,
            "center": {
               "latitude": -90,
               "longitude": -180
                }
            }
          }
        }
    }'

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": {
    "location_verification": {
        "is_verified": "TRUE",
        "latest_location_at": "2024-07-08T09:30:27.504Z",
        "match_rate": 1,
        "status": {
          "code": "NO_COVERAGE",
          "message": "Success"
        }
    }
  }
}

You'll see the following fields in the location_verification array:

Further Reading

• Read more about the Identity Insights API in the API Reference.
• If you have any questions, you can reach out to us on the Vonage Community Slack.