location_verification

The location_verification command verifies whether a mobile device is currently located within a specified circular geographic area. It validates presence against a center point (latitude and longitude) and a radius supplied in the request, returning a definitive match verdict based on real-time mobile network infrastructure data.

Because the position is determined directly from mobile network operator (MNO) radio and core network data rather than device GPS, the result is resistant to GPS spoofing, emulator overrides, VPN routing, and handset tampering. This makes location_verification a high-trust, privacy-preserving signal for transaction security, such as verifying card-present transactions at point-of-sale (POS) terminals, ATM withdrawals, and secure geofenced authentication.

Request Reference

To invoke location_verification, include the command in the commands array and provide the target area in the location_area object:

latitude: Decimal degrees of the center point (between -90.0 and 90.0). Required.
longitude: Decimal degrees of the center point (between -180.0 and 180.0). Required.
radius: The radius of the target circle in meters. Required. Minimum value is 1 meter.
max_age: Optional integer specifying the maximum acceptable age of the location fix in seconds. Where omitted, the MNO applies its own default. When specified, the minimum accepted value is 60 seconds.

The location_area object is mandatory for location_verification. If the request omits the object or lacks complete coordinates, the request is rejected and no supplier call is made.

Access requires authorization. Unauthorized requests are handled based on the query structure:

Partial Authorization: When querying multiple commands and location_verification is unauthorized for your API key, the location_verification block is omitted from the response and the command is not billed.
Command-Level Failure: If multiple requested commands fail or are unauthorized, the service returns Status 2 with a composite status message detailing the affected commands.
Single Command Failure: If location_verification is the only command requested and is unauthorized or the device cannot be served, the service returns Status 2.

Response Reference

Field Name	Data Type	Output Values	Description
location_verification	JSON Block	{verification data}, Omitted	Container block for the location verification verdict. Omitted if the command was not requested, unauthorized, or not served by the operator.
verification_result	String	TRUE, FALSE, PARTIAL, UNKNOWN	Primary match verdict returned by the mobile network operator: TRUE: The device is confirmed to be within the specified target area. FALSE: The device is confirmed to be outside the specified target area. PARTIAL: The device's estimated radio footprint partially overlaps with the specified area, so match certainty cannot be fully confirmed or denied. UNKNOWN: The device could not be located on the mobile network.
match_rate	Number	0–100, Omitted	Estimated percentage overlap between the network-estimated device coverage and the target area. Returned only when verification_result is `PARTIAL`. Omitted when the result is TRUE, FALSE, or UNKNOWN.
last_location_time	String	ISO 8601 UTC timestamp, Omitted	Timestamp indicating when the device's network location fix was recorded by the mobile operator. Omitted if the network fix timestamp is unavailable.

Summary Table

Command	Description	Response Values
`location_verification`	Verifies whether a mobile device is located within a specified circular area using MNO radio network data, without revealing the device's actual coordinates.	verification_result: TRUE, FALSE, PARTIAL, UNKNOWN match_rate: 0–100 (when PARTIAL) last_location_time: ISO 8601 UTC timestamp

API reference

Request

curl -X POST "https://api.connect.plumma.it/services/api" \
  -H "Content-Type: application/json" \
  -H "x-plumma-connect-api-key: YOUR_API_KEY_HERE" \
-H "x-plumma-connect-app-id: YOUR_APP_ID_HERE" \
  -d '{
  "number": "+541122358032",
  "commands": [
    "location_verification"
  ],
  "location_area": {
    "latitude": -34.570518,
    "longitude": -58.396377,
    "radius": 2000,
    "max_age": 120
  }
}'

Response (within area)

{
  "number": "+541122358032",
  "status": 0,
  "status_message": "Response from one supplier - This response is for demo purpose only [cmd_enc=2097152] [{location_verification=SUPPLIER0 : Success}]",
  "location_verification": {
    "verification_result": "TRUE",
    "last_location_time": "2025-10-31T17:16:33.000Z"
  },
  "version": "1.0.2-20260608095239"
}

Response (outside area)

{
  "number": "+541122358032",
  "status": 0,
  "status_message": "Response from one supplier - This response is for demo purpose only [cmd_enc=2097152] [{location_verification=SUPPLIER0 : Success}]",
  "location_verification": {
    "verification_result": "FALSE",
    "last_location_time": "2025-10-31T17:18:01.000Z"
  },
  "version": "1.0.2-20260608095239"
}

Response (partial match)

{
  "number": "+541122358032",
  "status": 0,
  "status_message": "Response from one supplier - This response is for demo purpose only [cmd_enc=2097152] [{location_verification=SUPPLIER0 : Success}]",
  "location_verification": {
    "verification_result": "PARTIAL",
    "match_rate": 25,
    "last_location_time": "2025-10-31T17:24:53.000Z"
  },
  "version": "1.0.2-20260608095239"
}

Response (device not found)

{
  "number": "+541100000000",
  "status": 0,
  "status_message": "Response from one supplier - This response is for demo purpose only [cmd_enc=2097152] [{location_verification=SUPPLIER0 : OK}]",
  "location_verification": {
    "verification_result": "UNKNOWN"
  },
  "version": "1.0.2-20260608095239"
}

Read this in the portal, with search and the reference beside it: Location Verification