Add a subject with Analyst Assistance

Use this workflow when Analyst Assistance is enabled for your organization. This is an organization service configuration, not a mode an API developer selects independently. Confirm it with your Ferretly contact before integrating.

Do not call initiateBackgroundCheck

Analyst Assistance integrations must not call initiateBackgroundCheck. Ferretly analysts manage the subject’s screening and review. Calling that endpoint interferes with the analyst-managed workflow.

1. Register status callbacks

Configure your receiver using Webhook setup before submitting subjects. Follow Analyst Assistance status callbacks and flow for the review-specific events and Mermaid diagram.

2. Create and assign the subject

POST /api/Subjects accepts a NewSubject and returns a Subject with HTTP 200. The following request saves a real subject and requests analyst work in your organization’s data. Use approved test details and coordinate testing with your Ferretly contact.

{
  "subjectData": {
    "name": "Example Candidate",
    "city": "Example City",
    "country": "US",
    "email": "candidate@example.com"
  },
  "externalSystemId": "candidate-001",
  "assignToFerretlyAnalyst": true,
  "isDebug": false
}

Supply available identity details and known social profiles. Ferretly handles identity resolution; your integration does not need to wait for a verified handle before assigning the subject. The Subjects guide explains profile fields, duplicate handling, limits, optional notes and create errors.

Store the returned id and your externalSystemId for callbacks and result retrieval. A successful create confirms subject creation, not completed analysis.

Your integration and the analyst

1. 01
   Your integrationSubmit and assign

   Create the subject with analyst assignment enabled for your organization.

2. 02
   Ferretly analystResolve identity and manage screening

   The analyst manages the workflow and reviews the findings. Your integration must not call initiateBackgroundCheck.

3. 03
   Your callback receiverReceive reviewed completion

   Handle Redressing, then the Redressed and Complete notifications. Retrieve the completed results and report.

3. Receive processing and review updates

Use callbacks to follow progress. Redressing means analyst review is outstanding. Redressed and Complete are the completion notifications associated with reviewed work; process them idempotently so receiving both does not duplicate your completion action.

Do not repeatedly fetch the subject to wait for profile verification or recheck every status notification. The status flow explains which events to handle.

4. Retrieve results and the report

After reviewed completion, retrieve results, posts and the report. Report generation or regeneration can briefly affect report availability; handle it separately from workflow completion.

Keep the analyst workflow in control

Do not call initiateBackgroundCheck to recover from a missing callback or a report that is not ready. Contact Ferretly Integrations about an unexpected workflow state.

Testing subject creation

Ferretly does not provide a separate integration test environment. Requests use your organization’s data. For a request-shape check, use the debug quickstart with analyst assignment disabled. Debug responses do not represent saved subjects, and using their IDs in a later lookup returns an error.

For a real analyst-assisted test, arrange the work with your Ferretly contact. Do not enable continuous screening during subject-creation testing unless isDebug is true.