Screening lifecycle without Analyst Assistance

This page is only for organizations without Analyst Assistance. Your organization’s Ferretly service configuration determines which workflow applies.

1. Register your callback

Set up status callbacks before submitting work. The flow without Analyst Assistance shows the processing and completion notifications to expect.

2. Create a subject

POST /api/Subjects accepts a NewSubject body and returns a Subject with HTTP 200. The following example saves a real subject in your organization’s data. Replace the example identity and use approved test details.

{
  "subjectData": { "name": "Example Candidate" },
  "externalSystemId": "candidate-001",
  "assignToFerretlyAnalyst": false,
  "isDebug": false
}

Supply known profiles using named URL fields or handles. The Subjects guide explains these inputs, duplicate handling, per-platform limits, ownership, Notes and create error responses.

Store the returned id. A name-only record has no verified social handle and cannot yet be screened through this workflow. For request-shape testing without saving a subject, use the debug quickstart.

3. Confirm the screening prerequisites

Before your integration starts a screening, confirm the saved subject has at least one verified social handle. An initially returned handle can still be awaiting validation. If necessary, retrieve the subject to inspect handleList; do not build a repeated status-polling loop.

The subject must not already have a screening in progress or participate in continuous screening. Applicable credit checks must also pass.

4. Start the screening once

curl --fail -sS "https://api.ferretly.com/api/Subjects/SUBJECT_ID/initiateBackgroundCheck" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

This GET changes state and can consume credits. A timeout does not establish that the action failed. Reconcile an uncertain result before considering another request.

Response	Meaning / next action
`200` with `InQueue`	The queue attempt succeeded; follow callbacks
`200` with `Error`	The initiation attempt failed; investigate the returned status
`400`	Subject missing or not valid for the client, no eligible verified social handles, work already in progress, recurring screening enabled, or applicable credit checks failed
`401` / `403`	Authentication or access prevents the request
`5xx` / network failure	Outcome may be uncertain; reconcile before retrying

See Start a screening for the published response contract and Errors and status codes for shared error handling.

5. Receive processing and completion callbacks

Use the delivered InQueue, InProgress, Complete or Error status. You do not need to fetch the same status again after each notification. This workflow does not include analyst-review stages.

See status callbacks and the Mermaid flow. If an expected update is missing, contact Ferretly Integrations rather than repeatedly polling.

6. Retrieve results and download the report

After Complete, retrieve aggregated results and detailed posts, then download the report when available:

GET /api/Subjects/{subjectId}/backgroundCheckResults
GET /api/Subjects/{subjectId}/filteredPosts
GET /api/Subjects/{subjectId}/downloadBackgroundReport

The Results and reports guide explains external-ID alternatives, post filters, binary downloads and operation-specific errors. Report regeneration can temporarily prevent a download; do not start another screening solely because a report is not ready.

Reconcile uncertain writes

Keep identifiers, the request timestamp, HTTP status and a redacted error summary. Before retrying creation or initiation after an uncertain outcome, check whether the subject or run already exists. External IDs support lookup but do not prevent duplicates.