Status callbacks with Analyst Assistance

This flow applies to organizations with Analyst Assistance. Register a receiver using Webhook setup, then create and assign subjects.

Analyst Assistance integrations must not start the screening

Do not call initiateBackgroundCheck. Ferretly analysts manage the workflow, including identity resolution and review.

Callback format

Ferretly sends an HTTP GET with subjectId, status, and externalSystemId query parameters. There is no JSON body.

GET /hooks/ferretly?subjectId=11111111-1111-4111-8111-111111111111&status=Redressed&externalSystemId=candidate-001 HTTP/1.1

Status	Meaning
None	No screening run has started
InQueue	The subject is queued for processing
InProgress	Processing is underway
Redressing	Processing has finished; analyst review is outstanding
Redressed	The analyst has marked the subject as reviewed
Complete	The successful workflow, including required review, is complete
Error	Processing failed; investigate with Ferretly before taking recovery action

Redressed and Complete describe reviewed completion and are sent together in this workflow. Accept both without performing your completion action twice. Do not rely on receiving every intermediate event or on a fixed delivery order. Use the status in the notification; there is no need to call the status endpoint again for each callback.

Flow

Background check flow with Analyst Assistance

Mermaid diagram source

sequenceDiagram
    accTitle: Background check with Analyst Assistance
    accDescr: The integration creates a subject. Ferretly and its analyst manage processing and review, notifying the integration through status callbacks.
    participant Client as Your integration
    participant API as Ferretly API
    participant Analyst as Ferretly analyst
    Client->>API: Add subject with analyst assignment
    API-->>Client: New subject response
    API->>Analyst: Assign subject
    Analyst->>API: Resolve identity and prepare screening
    Note over API,Analyst: Analyst manages the screening
    API-->>Client: Webhook InQueue
    API-->>Client: Webhook InProgress
    Note over API: Process screening
    API-->>Client: Webhook Redressing
    API->>Analyst: Findings ready for review
    Analyst->>API: Review findings and mark redressed
    API-->>Client: Webhook Redressed
    API-->>Client: Webhook Complete
    Note over Client: Both completion notifications describe reviewed work
    Client->>API: Retrieve results and report

The diagram adapts the existing Analyst Assistance status flow. Error outcomes can occur during processing; the successful path is shown above. Report readiness remains separate from the completion notification.

Planned identity-resolution notifications

Upcoming capability

Ferretly plans an additional webhook for identity-resolution events, including a profile being found, agentic search completing, and an analyst marking profiles reviewed. This is not part of the current screening-status callback contract. Confirm availability, registration and payload details with Ferretly before implementing it.

These events will describe identity-resolution progress, not replace the reviewed-completion statuses above. Do not build a polling loop while waiting for the planned webhook.

After completion

Retrieve results and reports from your authenticated backend. If a callback is missing or a state looks unexpected, contact Ferretly Integrations. Do not call initiateBackgroundCheck for an Analyst Assistance subject.