Get identification
shieldlabs_get_identificationRead the verdict of one identification from the ShieldLabs History API by request ID, returning risk score, band, signals, detection flags, and visitor/device details.
Instructions
Read the verdict of one identification by its request ID from the ShieldLabs History API: Risk Score and band, weighted risk signals, the 19 detection flags, visitor, device, cookie and session IDs, User HID, public and local IP with country, connection type, OS, browser and traffic source.
Use it when you have the request ID of a protected action (signup, login, payment) and need its verdict. The browser only ever sees the request ID; the verdict is read here, server-side.
Scoring is asynchronous: the History row appears about 1 to 3 seconds after the browser call and can be refined for up to about 10 seconds while follow-up checks finish. This tool returns the first version of the row it finds. A verdict read in those first seconds can still be refined: read it again (wait=false is enough) once observed_at is about 10 seconds in the past for the final state. Integrations that start the identification when the user begins the action (for example on the first interaction with a form) find the row stored by the time the action reaches their backend.
With wait=true it polls for up to about 10 seconds in total. A 429, a 5xx or a network error does not end the wait (its error is returned only when the last poll failed); a wrong key or base URL ends it at once.
Args:
request_id (string): UUID returned by the browser agent
wait (boolean): poll until the verdict is stored, for up to about 10 s in total (default true); false reads once
response_format ('markdown' | 'json'): default 'markdown'
Returns (json): { "found": true, "identification": { request_id, visitor_id, device_id, session_id, cookie_id, user_hid, domain, public_ip: { ip, country }, local_ip: { ip, country }, connection_type, os, browser, device_type, traffic_source: { channel, referrer_domain, landing_url, click_id_type, utm_source, utm_medium, utm_campaign, utm_content, utm_term }, risk_score, risk_band, signals: [{ name, weight, description: null }], detection_flags: { vpn, proxy, tor, ... }, observed_at, source, truncated_fields?, escaped_fields? }, "untrusted_data_note": string }
Errors: an error result when no identification is stored for the request ID (treat it as unverified, never as clean), when the key is wrong (401), or when the rate limit (429) or a server or network error prevents the read.
Next steps: shieldlabs_explain_risk_score explains the score; shieldlabs_summarize_entity with the device_id or user_hid shows the history around it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | Wait for the verdict when the identification is not stored yet, polling for up to about 10 seconds in total (default true). Use false to read once, for example to read a refined verdict again. | |
| request_id | Yes | Request ID of one identification: the UUID the browser agent returned for the protected action, for example "02f1d973-84db-4156-a7f7-e799e6bf389b" | |
| response_format | No | Output format: 'markdown' (default) for readable text, 'json' for structured data | markdown |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| found | Yes | ||
| identification | Yes | ||
| untrusted_data_note | Yes |