Data Structures

Contained here is a list of example structures you can expect to see on various API responses.

IncidentStructure

The incident structure represents the simplest incident structure returned by the API.

{
    "id": string,
    "clientId"?: string,
    "safeDomain": string,
    "subject"?: string, // resolved display name: URL, domain, email, phone, or IP
    "incidentType": string,
    "domain"?: string, // only present on "domain" incidentType if "url" path differs from domain
    "url"?: string, // only present if URL differs from domain or if incidentType is social
    "source": string,
    "status": string, // see Status Values below
    "timestamp": Date,
    "lastHistoryUpdateTimestamp"?: Date, // date of the most recent status change
    "burnStartedTimestamp"?: Date, // date when takedown process started
    "takedownTimestamp"?: Date, // date when takedown concluded successfully
    "reportedBy"?: string, // email of the user who reported the incident
    "threatTaxonomy"?: ThreatTaxonomy, // threat classification (see below)
    "incidentClass": string // broad incident classification (e.g. "phishing", "infringement", "n/a")
}

Info

Every incident will have either a url OR domain field present, in some cases both may be present. But it should be noted that either of them may be undefined depending on the domain name structure and incidentType.

Status Values

The status field returns a computed verbose status value. The possible values are:

Status	Description
pending_review	Incident has been reported but not yet reviewed by an analyst.
case_building	Analyst is reviewing the incident, choosing a plan of action and gathering evidence.
approval_required	Incident is in case building and the takedown is pending approval.
takedown_ready	Incident is in case building and the takedown has been approved.
pre_weaponised	Incident has been placed into monitoring.
takedown_in_progress	Takedown process has been initiated but not yet completed.
takedown_success	Takedown has been completed successfully.
takedown_attempt_failed	Takedown was attempted but failed.
blocklisted	Incident has been blocklisted (no takedown performed).
action_required	Incident is awaiting action from the client.
closed	Incident is resolved/closed.

DetailedIncidentStructure

The detailed incident inherits all fields from IncidentStructure but appends additional fields including history, incidentState, registrar, and hostingProvider:

{
    "id": string,
    "clientId": string,
    "safeDomain": string,
    "subject"?: string,
    "incidentType": string,
    "domain"?: string, // only present on "domain" incidentType
    "url"?: string, // only present if URL differs from domain
    "source": string,
    "status": string, // see Status Values above
    "timestamp": Date,
    "lastHistoryUpdateTimestamp"?: Date,
    "burnStartedTimestamp"?: Date,
    "takedownTimestamp"?: Date,
    "reportedBy"?: string,
    "threatTaxonomy"?: ThreatTaxonomy, // expanded format (see ThreatTaxonomy)
    "incidentClass": string,
    "history": IncidentHistory[],
    "incidentState": IncidentState,
    "registrar"?: Registrar, // registrar info with takedown difficulty
    "hostingProvider"?: string // hosting provider name
}

Info

Every incident will have either a url OR domain field present, in some cases both may be present. But it should be noted that either of them may be undefined depending on the domain name structure and incidentType.

ThreatTaxonomy

The threat taxonomy classifies the type of threat an incident represents. This field is present when a threat classification has been assigned.

The list endpoint (GET /incidents) returns a lite format:

{
    "name": string, // taxonomy name (e.g. "Brand - Website - Impersonation")
    "description": string // additional description (may be empty)
}

The detail endpoint (GET /incident/{id}) returns an expanded format with additional classification fields:

{
    "name": string, // taxonomy name (e.g. "Brand - Website - Impersonation")
    "description": string, // additional description (may be empty)
    "incidentClass"?: string, // broad classification (e.g. "phishing", "infringement")
    "incidentTargetType"?: TypeReference, // target type classification
    "incidentType"?: TypeReference, // incident type classification
    "incidentThreatType"?: TypeReference // threat type classification
}

TypeReference

Sub-objects within the expanded threat taxonomy use the following structure:

{
    "id": string,
    "name": string,
    "description": string
}

Registrar

The registrar object provides information about the domain registrar and its estimated takedown difficulty. This field is only present on the detail endpoint when registrar data is available.

{
    "name"?: string, // registrar name
    "difficulty"?: string, // takedown difficulty level
    "description"?: string // description of the difficulty level
}

IncidentState

The incident state is a structure for reflecting the real-time state of an incident (whether or not it's responsive, has a warning banner, etc).

{
    "unresponsive": boolean, // the incident is not responding to requests
    "warningBanner": boolean, // a Google SafeBrowsing or Cloudflare warning banner is displayed
    "responsive": boolean, // the incident is responding to requests
    "contentRemoved": boolean, // the malicious content on the page has been removed
    "redirect": boolean,
    "inconclusive": boolean, // the state could not be determined
    "timestamp": Date // the timestamp of the last state scan
}

IncidentHistory

The incident history is a time-based entry of incident state change info.

{
    "timestamp": Date,
    "message": string,
    "type": "info" | "action"
}

PagingStructure

The paging structure is returned by list endpoints that support pagination. It provides cursor-based pagination for efficient navigation through large result sets.

{
    "cursor": string, // current cursor position (typically the ID of the last item in the current page)
    "next": string | null, // cursor for the next page, null if no more results
    "limit": number // number of items per page
}

Usage

• Use the next value as the cursor query parameter in your subsequent request to fetch the next page
• When next is null or absent, you have reached the end of the results
• The default limit is 5000 if not specified in the request