Get results by external ID

GET /api/Subjects/getByExternalId/{externalId}/backgroundCheckResults

Authentication

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

Returns 400 if there is no completed screening or a screening is in progress. See Results and reports.

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/getByExternalId/candidate-001/backgroundCheckResults" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

const response = await fetch("https://api.ferretly.com/api/Subjects/getByExternalId/candidate-001/backgroundCheckResults", {
  "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/getByExternalId/candidate-001/backgroundCheckResults",
    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/getByExternalId/candidate-001/backgroundCheckResults");
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
`externalId`	path	Yes	string

Responses

200

Success

text/plain: BackgroundCheckResults
application/json: BackgroundCheckResults
text/json: BackgroundCheckResults

400

Something was invalid about the request: subject does not have a completed background check; subject currently has background check in-progress

text/plain: string
application/json: string
text/json: string

404

Subject was not found

Response example

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

{
  "initiated": "2026-10-14T12:00:00Z",
  "subjectId": "11111111-1111-4111-8111-111111111111",
  "subjectExternalSystemId": "candidate-001",
  "flaggedPosts": 0,
  "flagCount": 0,
  "totalPosts": 12,
  "riskMakeups": [],
  "channelVolumes": [],
  "score": 0,
  "totalSentiment": 0.2,
  "isRedressed": false
}

Response properties

Property	Type	Description
`initiated`	string (date-time)	When the background check was initiated
`subjectId`	string (uuid)	The Ferretly subject ID
`subjectExternalSystemId`	string	The subject’s external system ID (if provided). Nullable.
`riskMakeups`	array of RiskMakeup	Risk makeups: count of posts flagged for each risk Nullable. Read-only response field.
`channelVolumes`	array of ChannelVolume	Count of posts found per-platform Nullable.
`flaggedPosts`	integer (int32)	Count of flagged posts
`flagCount`	integer (int32)	Total number of flags found in Not necessarily the same value as FlaggedPosts
`totalPosts`	integer (int32)	Count of posts found Read-only response field.
`webSearchPosts`	integer (int32)	Count of web search posts found
`score`	integer (int32)	Calculated score
`totalSentiment`	number (double)	The total sentiment (sum of sentiment from all posts)
`finishedScraping`	string (date-time)	When the post fetcher completed fetching the last post Nullable.
`runStatus`	RunStatusEnum
`isRedressed`	boolean	A boolean indicating whether this subject has been “marked as redressed”
`lastMarkAsRedressedOn`	string (date-time)	The most recent time the subject was “marked as redressed”. Will be null if the subject has not been “marked as redressed” Nullable.
`postSummaryText`	string	A string that represents AI-generated text that summarizes the subject’s most-recent flagged posts Nullable.

riskMakeups properties

Property	Type	Description
`riskName`	string	The name of the behavior Nullable.
`count`	integer (int32)	Count of the number of posts flagged for this behavior

channelVolumes properties

Property	Type	Description
`channelName`	string	Nullable.
`count`	integer (int32)
`flaggedPosts`	integer (int32)	Nullable.