Skip to content
Ferretly Ferretly Ferretly Docs API
Request API key

Status callbacks without Analyst Assistance

Use this flow only when your organization operates without Analyst Assistance. Your integration follows the screening lifecycle and starts the screening after confirming its prerequisites. For an organization with Analyst Assistance, use the analyst-managed flow instead.

Callback format

Section titled “Callback format”

Register your receiver through Webhook setup. 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=Complete&externalSystemId=candidate-001 HTTP/1.1
StatusMeaning
NoneNo screening run has started
InQueueScreening is queued
InProgressScreening is processing
CompleteThe screening completed successfully; retrieve results
ErrorProcessing failed; investigate before considering another attempt

This flow does not include analyst-review stages. Use the status delivered in the callback rather than fetching the same status again. Handle duplicate notifications idempotently, and do not assume a fixed delivery order or that every intermediate status will be delivered.

Flow

Section titled “Flow”
Background check flow without Analyst Assistance
Mermaid diagram source 
sequenceDiagram
    accTitle: Background check without Analyst Assistance
    accDescr: The integration creates a subject, confirms a verified handle, starts a screening once, and receives processing and completion callbacks.
    participant Client as Your integration
    participant API as Ferretly API
    Client->>API: Add subject
    API-->>Client: New subject response
    Note over Client: Confirm at least one verified handle
    Client->>API: Initiate background check once
    API-->>Client: Webhook InQueue
    API-->>Client: Webhook InProgress
    Note over API: Process screening
    API-->>Client: Webhook Complete
    Client->>API: Retrieve results and report

The diagram adapts the existing flow without Analyst Assistance. It shows the successful path; a processing failure produces Error. Confirm a saved subject has at least one verified handle before the single initiation call.

After completion

Section titled “After completion”

Retrieve results, posts and the report through your authenticated backend. Handle temporary report unavailability separately; do not create another screening just to regenerate a report.