AbuseZeroAbuseZero

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" }
  ]
}
FieldTypeDescription
object"lookup"The object type.
typeid, email, ip or nullWhat the value was read as. null when it's none of the three, and matches is empty.
matchesarray of objectsWhat 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.

kindFound byFields
evaluationAn evaluation IDid, result (allow or deny) and benefit, the benefit's key.
evaluationsAn email address, or a 20-digit claim ID or user IDcount 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_historyAn email address, or a 20-digit claim ID or user IDcount 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.
benefitA benefit IDid, key and name.
policyA custom policy IDid, key and name.
protection_levelA protection level's IDid, key and name.
access_list_entryAn entry ID, or a value that's listedid, list (allow or block) and type, the entry type. Never the listed value.
api_keyAn API key IDid and name.
webhook_endpointA webhook endpoint IDid and url.
memberA member's ID, or the email address of a memberid and email. See Members.
importAn import IDid and file_name, or null.
custom_identifierA custom identifier IDid 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.

MethodPathScopeIdempotency-Key
POST/v1/identifiers/lookupoperations:generalNot 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

FieldTypeRequiredLimitsDescription
valuestringYes1 to 254 charactersA 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

CodeStatusMeaning
INVALID_FIELD422value is missing, empty or longer than 254 characters.

For every other code, see REST API errors.

How is this guide?

Last updated on