Lookup
Find what a 20-digit ID, an email address or an IP address names in your workspace.
A lookup takes one value you have, such as an ID from a log, a customer's email address or an IP address, and returns what it names in your workspace: the record an ID belongs to, the allow and block list entries that match the value, how many evaluations in the last 90 days found it, and how many claims in your claim history it finds. It runs the same search as the dashboard's search box (⌘K on a Mac, Ctrl K elsewhere), which shows everything except the claim history count. A lookup changes nothing and never returns a list entry's value.
Examples on this page use a server client:
import { AbuseZero } from "abusezero/server";
const abusezero = new AbuseZero({ key: process.env.ABUSEZERO_SECRET_KEY!, outage: "throw" });The lookup object
{
"object": "lookup",
"type": "email",
"matches": [
{ "object": "lookup_match", "kind": "evaluations", "count": 3, "capped": false, "days": 90 },
{ "object": "lookup_match", "kind": "claim_history", "count": 4, "capped": false },
{ "object": "lookup_match", "kind": "access_list_entry", "id": "39408249715658343608", "list": "block", "type": "email" }
]
}| Field | Type | Description |
|---|---|---|
object | "lookup" | The object type. |
type | id, email, ip or null | What the value was read as. null when it's none of the three, and matches is empty. |
matches | array of objects | What the value names or matches, by kind. Empty when nothing matches. |
Match kinds
Every match has object: "lookup_match" and a kind. The other fields depend on the kind.
kind | Found by | Fields |
|---|---|---|
evaluation | An evaluation ID | id, result (allow or deny) and benefit, the benefit's key. |
evaluations | An email address, or a 20-digit claim ID or user ID | count of evaluations in the last days (90) that the value finds, as List evaluations finds them with query. capped is true when there are more than 1,000, and count is then 1,000. |
claim_history | An email address, or a 20-digit claim ID or user ID | count of claims in your claim history that the value finds: delivered claims, whether an evaluation, an outcome report or an import recorded them. Claim history isn't limited to 90 days. capped is true when there are more than 1,000, and count is then 1,000. |
benefit | A benefit ID | id, key and name. |
policy | A custom policy ID | id, key and name. |
protection_level | A protection level's ID | id, key and name. |
access_list_entry | An entry ID, or a value that's listed | id, list (allow or block) and type, the entry type. Never the listed value. |
api_key | An API key ID | id and name. |
webhook_endpoint | A webhook endpoint ID | id and url. |
member | A member's ID, or the email address of a member | id and email. See Members. |
import | An import ID | id and file_name, or null. |
custom_identifier | A custom identifier ID | id and key. |
Treat an unfamiliar kind as valid, because new ones can be added within v1.
Members
A member's email shows in full only to a person signed in with the Reveal personal identifiers permission, and to the member themselves. Everyone else gets it partly hidden, as in Members & access. Only a person with that permission finds members by their email address. API keys and machine clients act for no person, so they get member emails partly hidden and don't find members by email.
Look up a value
Returns the lookup object for one value. The value travels in the request body, so it never appears in a URL.
| Method | Path | Scope | Idempotency-Key |
|---|---|---|---|
POST | /v1/identifiers/lookup | operations:general | Not used |
Also available as abusezero identifiers lookup in the AbuseZero CLI, abusezero_look_up_identifier on the AbuseZero MCP server and lookUpIdentifier() in the AbuseZero Node.js SDK.
Request body
| Field | Type | Required | Limits | Description |
|---|---|---|---|---|
value | string | Yes | 1 to 254 characters | A 20-digit ID, an email address or an IP address. Spaces around it are ignored. |
Example
const lookup = await abusezero.lookUpIdentifier("jordan@example.com");Response
Returns 201 with a lookup object.
{
"object": "lookup",
"type": "email",
"matches": [
{ "object": "lookup_match", "kind": "evaluations", "count": 3, "capped": false, "days": 90 },
{ "object": "lookup_match", "kind": "claim_history", "count": 4, "capped": false },
{ "object": "lookup_match", "kind": "access_list_entry", "id": "39408249715658343608", "list": "block", "type": "email" }
]
}An ID from another workspace, or one that names nothing, returns no match for that ID. To read the evaluations an email address found, list evaluations with query set to it and days=90.
Errors
| Code | Status | Meaning |
|---|---|---|
INVALID_FIELD | 422 | value is missing, empty or longer than 254 characters. |
For every other code, see REST API errors.
Related
How is this guide?
Last updated on