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
}

UserStructure

The user structure represents a dashboard user returned by the Users endpoint. Only client-safe fields are exposed.

{
    "id": string,
    "email": string,
    "name"?: string, // first name (may be null/absent)
    "surname"?: string, // last name (may be null/absent)
    "roles": string[], // see User Roles below
    "clientId"?: string, // the client the user belongs to (absent for staff/admins)
    "clientName"?: string, // display name of the user's client
    "mfaEnabled": boolean, // whether multi-factor authentication is enabled
    "createdAt": Date, // when the user was created
    "updatedAt": Date // when the user was last updated
}

User Roles

The roles array on a UserStructure contains one or more of the following values:

Role	Description
`superuser`	Administrator for the client account (manage users, settings, and documents).
`parentadmin`	Administrator across a parent/reseller account and its managed sub-clients.
`user`	Standard dashboard user.
`admin`	PhishFort-internal administrator role. Accepted as a filter value but internal users are excluded from client API responses.

PhishFort internal accounts are never returned

PhishFort staff accounts — identified by the internal admin role or a @phishfort.com email address — are excluded from this endpoint. Only your own account's users are returned.

ClientStructure

The client structure represents a client account returned by the Clients endpoint.

{
    "id": string, // the client's unique ID
    "name": string, // the client's display name
    "active": boolean // whether the client account is active
}

DocumentStructure

The document structure represents a document on file, returned by the Documents endpoints. The single-document detail endpoint additionally includes a short-lived signedUrl.

{
    "id": string, // the document's unique ID
    "clientId": string, // the client the document belongs to
    "client": { // reference to the owning client (null if unavailable)
        "id": string,
        "name": string,
        "parentClientId": string | null
    } | null,
    "docType": string, // see Document Types below
    "fileName": string | null, // original file name
    "uploadedBy": { // who uploaded the document (null if unavailable)
        "id"?: string,
        "email"?: string,
        "name"?: string,
        "surname"?: string
    } | null,
    "createdAt": Date | null, // when the document was uploaded
    "updatedAt": Date | null, // when the document was last updated
    "signedUrl"?: string | null // temporary download URL (detail endpoint only)
}

Document Types

The docType field on a DocumentStructure is one of the following values:

Type	Description
`loa`	Letter of Authorisation.
`trademark_registration`	A trademark registration certificate or filing.
`exec_loa`	An executive-specific Letter of Authorisation.
`file`	A general supporting file.

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
    "count": number, // number of items in the current page
    "total": number // total number of items matching the query across all pages; only present when includeTotal=true is requested
}

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
Pass includeTotal=true to include the total field (supported on GET /incidents)