Results and reports

Wait for workflow completion

Use completion callbacks before retrieving results. With Analyst Assistance, Redressing means review is outstanding; Redressed and Complete notify you of reviewed completion. Without Analyst Assistance, Complete indicates successful processing. Handle duplicate completion notifications idempotently.

Use the status delivered in the notification; a status recheck after each callback is unnecessary.

Retrieve aggregated results

GET /api/Subjects/{subjectId}/backgroundCheckResults
GET /api/Subjects/getByExternalId/{externalId}/backgroundCheckResults

Results describe the most recently completed screening. The endpoint returns 400 when there is no completed screening or a screening is currently in progress. Do not depend on retrieving an older result while a new screening is running.

Keep the returned subject identifier and available timestamps aligned with the workflow you are tracking. The API does not advertise a run-ID parameter on these endpoints.

Field	Meaning
`subjectId`	Ferretly subject identifier
`subjectExternalSystemId`	Your external identifier, when supplied
`initiated`	When the returned screening was initiated
`score`	Calculated screening score
`flaggedPosts`	Count of posts with flags
`flagCount`	Total number of flags, which can differ from flagged-post count
`riskMakeups`	Flag counts grouped by risk
`channelVolumes`	Post counts by platform
`totalPosts`	Total post count
`runStatus`	Detailed `RunStatusEnum`, distinct from workflow `BackgroundCheckStatus`
`postSummaryText`	Optional AI-generated summary of recent flagged posts
`isRedressed`	Whether the subject was marked as reviewed
`lastMarkAsRedressedOn`	Most recent review timestamp, when present

See BackgroundCheckResults for the complete schema. Aggregated results do not contain a collection of full flagged-post payloads.

Retrieve posts

GET /api/Subjects/{subjectId}/filteredPosts
GET /api/Subjects/{externalId}/filteredPostsByExternalId

Both return arrays of Post. See Posts and media to interpret authorship, sentiment, keywords, and media-level flags. Use these query parameters:

Parameter	Values	Default
`typeFilter`	`All`, `NegativeSentiment`, `PositiveSentiment`, `Flagged`, `WebNews`, `Tagged`, `SavedSearch`, `SanctionsSearch`	`All`
`dateFilter`	`None`, `ThirtyDays`, `SincePrevious`, `Custom`	`None`

Use the values exactly as shown. These endpoints do not accept a platform filter, start/end dates, or pagination parameters. Although Custom is a valid dateFilter value, you cannot supply a custom date range through these endpoints.

Example flagged-post request:

curl --fail -sS "https://api.ferretly.com/api/Subjects/SUBJECT_ID/filteredPosts?typeFilter=Flagged&dateFilter=None" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

The endpoint returns an empty post array when the subject has no most-recent run ID. An empty array is not proof that a completed screening found no posts.

Download a report

curl --fail -sS "https://api.ferretly.com/api/Subjects/SUBJECT_ID/downloadBackgroundReport" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -o report.bin

The response content type is application/octet-stream. Write it as binary, check the HTTP status, and use the response’s filename when supplied. Do not parse the file as JSON or infer its extension from the MIME type alone.

Status	Meaning
`200`	Binary report returned
`400`	No current report, or report is being regenerated
`404`	Subject or report file not found

Analyst review can regenerate the report. Treat temporary report unavailability separately from screening completion; do not rerun a screening just to recover a missing report.

See Download a report for response details.