Use the client SDK's device_token to query the device fingerprint and obtain device identification, device information, and risk signals. If client reporting fails, submit the raw SDK geetoken through the same endpoint for fallback analysis. See fp_query fallback mode.

Interface

Where to get input from

Supported clients

iOS, Android, and Web/H5.

Regional restrictions

Each application belongs to exactly one Region, configured in the dashboard. Send the request to the regional API endpoint for the application's Region.

Requests sent to a node in another Region return 404 with message: "integration not found".

Response envelope

Use Content-Type: application/json. The HTTP status code and JSON code have the same value.

Success:

{ "code": 200, "data": {}, "message": "Success" }

Failure:

{ "code": 400, "data": {}, "message": "Invalid request" }

When validation fails, data contains:

{
  "errors": [
    { "field": "device_token", "reason": "Field required", "type": "missing" }
  ]
}

Error code

POST /api/v2/fp_query/{public_key}

Query the device fingerprint. Send the device_token returned by the client SDK to retrieve trusted device attributes and risk signals.

Request

POST /api/v2/fp_query/{public_key}
Authorization: Bearer <secret>
Content-Type: application/json

Path

Headers

Body

{
  "device_token": "<from-client-sdk>",
  "event_type": "login",
  "event_time": "2026-08-20T10:30:00+08:00"
}

Minimum request body:

{ "device_token": "<from-client-sdk>" }

fp_query fallback mode

If the client SDK fails to report data or does not obtain a result token, send the raw geetoken generated by the SDK to your backend. The backend can then use the same POST /api/v2/fp_query/{public_key} endpoint to obtain the device fingerprint and risk signals.

Request method

• Continue using the device_token field and pass the raw SDK geetoken as-is. No additional field or mode parameter is required.
• Use the same URL, Bearer authentication, and optional parameters as a standard query. Send the request to the API endpoint for the application's Region. Keep secret on the backend and never expose it to clients.

Example for the Global endpoint (replace it with the North America or Europe endpoint when applicable):

curl -sS -X POST "https://riskct-global.geelabapi.com/api/v2/fp_query/{public_key}" \
  -H "Authorization: Bearer {secret}" \
  -H "Content-Type: application/json" \
  -d '{"device_token":"{sdk_raw_geetoken}"}'

The response structure is the same as a standard query; see Response (200). Successful fp_query requests in fallback mode are also billable.

Response (200)

{
  "code": 200,
  "data": {
    "request_id": "req_0198c7a1-5b2e-7c10-8d44-1234567890ab",
    "event_id": "evt_0198c7a1-5b2e-7c10-8d44-1234567890ab",
    "fp_detail": {
      "device_id": "GEE4-xxxxxx",
      "version": "1.0"
    },
    "signals": [
      {
        "signal": "CLOUD_PHONE",
        "level": "HIGH",
        "confidence": 0.8
      }
    ],
    "detail": {
      "client_type": "Android",
      "device_basic": {
        "os": "Android",
        "pla": "arm64-v8a",
        "mod": "Pixel 8",
        "osv": "14"
      },
      "ip_info": {
        "ip": "1.1.1.1",
        "ip_geo": {
          "country": "China",
          "subdivision": "Shanghai",
          "city": "Shanghai"
        }
      }
    }
  },
  "message": "Success"
}

data

fp_detail

signals[]

The following table lists the signal values and descriptions currently supported by the Server API.

Signal Reference (40+)

detail

If your server validates responses against a strict schema (for example, rejecting unknown fields), allow ip_info.ip_geo first.

Android/iOS device_basic:

{
  "os": "Android",
  "pla": "arm64-v8a",
  "mod": "Pixel 8",
  "osv": "14"
}

Web/H5device_basic:

{
  "browser": { "name": "Chrome", "version": "145.0.0.0", "major": "145" },
  "device": { "model": "Macintosh", "vendor": "Apple" },
  "os": { "name": "macOS", "version": "10.15.7" }
}

Error

The HTTP status code equals code. message is the exact string shown in the table below. For 403 responses, message is a stable reason code that your code can branch on; the response never includes expected allowlist values or the caller IP.

{
  "code": 400,
  "data": {
    "errors": [
      { "field": "device_token", "reason": "Field required", "type": "missing" }
    ]
  },
  "message": "Invalid request"
}

{
  "code": 401,
  "data": {},
  "message": "Invalid bearer token"
}

Example

Copy {public_key} and {secret} from the dashboard. Get {device_token} from the client SDK, and send the request to the regional API endpoint for the application's Region.

curl -sS -X POST "https://{host}/api/v2/fp_query/{public_key}" \
  -H "Authorization: Bearer {secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "device_token": "{device_token}",
    "event_type": "login",
    "event_time": "2026-08-20T10:30:00+08:00"
  }'