Start a screening (without Analyst Assistance)

GET /api/Subjects/{subjectId}/initiateBackgroundCheck

Authentication

Send your private API key in the X-Api-Key header. Keep it on your server.

Changes state: this GET performs an action. Do not automatically retry it after an uncertain response; verify the resulting state first.

The subject needs a verified social handle, must not already have a screening in progress, and must not participate in continuous screening. Credit checks also apply. Do not use this endpoint for Analyst Assistance; follow the analyst workflow.

Request example

Examples use illustrative values. Set FERRETLY_API_KEY in your server environment for JavaScript, Python, and C#. Replace sample IDs, URLs, and profile values before use.

curl --fail -sS -X GET "https://api.ferretly.com/api/Subjects/11111111-1111-4111-8111-111111111111/initiateBackgroundCheck" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch("https://api.ferretly.com/api/Subjects/11111111-1111-4111-8111-111111111111/initiateBackgroundCheck", {
  "method": "GET",
  "headers": {
    "X-Api-Key": process.env.FERRETLY_API_KEY,
    "Accept": "application/json"
  }
});
if (!response.ok) throw new Error("HTTP " + response.status);
console.log(await response.json());

import os
import requests

response = requests.request(
    "GET",
    "https://api.ferretly.com/api/Subjects/11111111-1111-4111-8111-111111111111/initiateBackgroundCheck",
    headers={"X-Api-Key":os.environ["FERRETLY_API_KEY"],"Accept":"application/json"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

using System;
using System.IO;
using System.Net.Http;
using System.Text;

using var http = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("GET"), "https://api.ferretly.com/api/Subjects/11111111-1111-4111-8111-111111111111/initiateBackgroundCheck");
request.Headers.Add("X-Api-Key", Environment.GetEnvironmentVariable("FERRETLY_API_KEY"));
request.Headers.Accept.ParseAdd("application/json");
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Parameters

Name	In	Required	Type	Description
`subjectId`	path	Yes	string (uuid)

Responses

200

Successfully attempted to start background check

text/plain: BackgroundCheckStatus
application/json: BackgroundCheckStatus
text/json: BackgroundCheckStatus

400

Subject does not exist or has no social media accounts associated with it, is not valid for the API client, already has a background check in progress, or organization does not have enough credits.

Response example

Illustrative, shortened HTTP 200 response. Optional fields can be absent or null.

"InQueue"

Response properties