curl 'https://account.shieldlabs.ai/api/v1/domains/7c9e6679-7425-40de-944b-e07fc1f90ae7/history/identifications/550e8400-e29b-41d4-a716-446655440000' \
-H "Authorization: Bearer $SHIELDLABS_API_KEY"
{
"data": {
"type": "identification",
"id": "550e8400-e29b-41d4-a716-446655440000",
"risk": {
"state": "ok",
"band": "suspicious",
"score": 30
},
"signals": {
"state": "ok",
"items": ["vpn"]
}
}
}
Methods
Read one history record
Read one identification, user, visitor, device, or IP.
GET
/
api
/
v1
/
domains
/
{domain_id}
/
history
/
{resource}
/
{resource_id}
curl 'https://account.shieldlabs.ai/api/v1/domains/7c9e6679-7425-40de-944b-e07fc1f90ae7/history/identifications/550e8400-e29b-41d4-a716-446655440000' \
-H "Authorization: Bearer $SHIELDLABS_API_KEY"
{
"data": {
"type": "identification",
"id": "550e8400-e29b-41d4-a716-446655440000",
"risk": {
"state": "ok",
"band": "suspicious",
"score": 30
},
"signals": {
"state": "ok",
"items": ["vpn"]
}
}
}
Reads one record.
A missing identification returns
A hostname,
List filters such as
History and webhooks have different field names:
The read does not consume identification quota. The History API allows 15 requests per second per domain.
{domain_id} comes from Domain. {resource} is identifications, user, visitor, device, or ip.
curl 'https://account.shieldlabs.ai/api/v1/domains/7c9e6679-7425-40de-944b-e07fc1f90ae7/history/identifications/550e8400-e29b-41d4-a716-446655440000' \
-H "Authorization: Bearer $SHIELDLABS_API_KEY"
{
"data": {
"type": "identification",
"id": "550e8400-e29b-41d4-a716-446655440000",
"risk": {
"state": "ok",
"band": "suspicious",
"score": 30
},
"signals": {
"state": "ok",
"items": ["vpn"]
}
}
}
Authentication
string
required
Bearer PRIVATE_API_KEY. Use the domain’s Private API Key.404. For a new Identification ID, use a bounded retry or an SDK retrieval helper. Bind the result to the expected domain, account and protected action before using it.
Path parameters
string
required
identifications, user, visitor, device, or ip.string
required
The record id. URL-encode it once. An IP is IPv4.
all, an empty id, . or .., a slash, a backslash, or a control character is rejected.
Query parameters
string
Only on a device record:
legacy or fp21_record.string
Linked records on this card, with
relation_limit and relation_page_token.from, to, risk_bands, and is_vpn also apply. See Search.
Response
One record returns{ "data": { ... } }. Successful responses also send History-Snapshot, History-Snapshot-Expires-At, History-Window-From, and History-Window-To.
object
required
The card. See History card.
| History card | Scored webhook data |
|---|---|
id when type is identification | identification_id |
risk.score when risk.state is ok | risk_score |
risk.band | Trusted, Suspicious or Dangerous label for that score |
signals.items | Signal names in signals. The webhook also includes each contribution. |
Errors
| Status | Code | Meaning |
|---|---|---|
400 | invalid_query / invalid_domain_scope / invalid_id | Bad parameter, hostname, or id |
401 | auth message | Missing or invalid Private API Key |
403 | domain_scope_not_supported | all is not a domain id |
404 | not_found / unknown_domain | No such record or domain |
429 | rate limit | Domain request limit reached |