Get a subject

GET /api/Subjects/{subjectId}

Authentication

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

Using the Subject Object’s Notes Field

The optional notes response field contains free-form notes about the subject. It can be null.

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

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

JavaScript

const response = await fetch("https://api.ferretly.com/api/Subjects/11111111-1111-4111-8111-111111111111", {
  "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());

Python

import os
import requests

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

C#

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");
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

Success

• text/plain: Subject
• application/json: Subject
• text/json: Subject

404

Subject was not found

Response example

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

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Example Candidate",
  "externalSystemId": "candidate-001",
  "status": "Active",
  "dateAdded": "2026-10-14T12:00:00Z",
  "handleList": [
    {
      "platform": "Twitter",
      "handle": "your_candidate",
      "profileUrl": "https://x.com/your_candidate",
      "verified": false,
      "status": "Unverified",
      "isPersonalProfile": true
    }
  ],
  "isAssignedToFerretlyAnalyst": false,
  "isExternalApiSubject": true,
  "notes": "Please review the supplied profile information."
}

Response properties

Property	Type	Description
id	string (uuid)
subscriberId	string (uuid)	The ID of the subscriber that added this subject or who currently “owns” it (see OwnerFirstName and OwnerLastName)
ownerFirstName	string	First name of the subscriber that added this subject or who currently “owns” it Nullable.
ownerLastName	string	Last name of the subscriber that added this subject or who currently “owns” it Nullable.
ownerEmail	string	Email of the subscriber that added this subject or who currently “owns” it Nullable.
ownerProfilePhotoUrl	string	Profile photo url of the subscriber that added this subject or who currently “owns” it Nullable.
organizationId	string (uuid)
name	string	Nullable.
nickname	string	Another name/alias property for the subject Nullable.
handles	string	Nullable.
handleList	array of SubjectHandle	Nullable.
mostRecentRunId	string (uuid)	Nullable.
dateAdded	string (date-time)	Nullable.
subjectAddedAuditInfo	AuditInfo
profilePicUrl	string	Nullable.
lastRunDate	string (date-time)	Represents the date/time that the most recent run completed Nullable.
score	integer (int32)	Nullable.
status	SubjectStatus
lastRunStatus	RunStatusEnum
lastRunStatusMessage	string	Nullable.
lastRunFinishedScraping	string (date-time)	Nullable.
currentRunStarted	string (date-time)	Nullable.
currentBackgroundCheckStartedBy	string	Nullable.
currentRunStatus	RunStatusEnum
currentRunId	string (uuid)	Nullable.
backgroundReportFileName	string	Gets and sets the name of a newly-generated background report file. Also sets IsBackgroundReportStale to false. Nullable.
isBackgroundReportStale	boolean	A Boolean to indicate that there have been data changes which cause the current background report file to be outdated
address	string	Nullable.
city	string	Nullable.
state	string	Nullable.
country	string	Nullable.
coordinates	GeoLocation
email	string	Nullable.
highSchool	string	Nullable.
college	string	Nullable.
company	string	Nullable.
phoneNumber	string	Nullable.
twitterUrl	string	Nullable.
facebookUrl	string	Nullable.
instagramUrl	string	Nullable.
linkedInUrl	string	Nullable.
tiktokUrl	string	Nullable.
redditUrl	string	Nullable.
pinterestUrl	string	Nullable.
youtubeUrl	string	Nullable.
tags	array of string	Nullable.
riskMakeups	array of RiskMakeup	Nullable.
channelVolumes	array of ChannelVolume	Nullable.
isRedressed	boolean
lastMarkAsRedressedOn	string (date-time)	Nullable.
lastMarkedAsRedressedBy	string (uuid)	Nullable.
lastMarkedAsRedressedEmail	string	Nullable.
lastMarkedAsRedressedName	string	Nullable.
lastMarkedAsRedressedAuditInfo	AuditInfo
totalPosts	integer (int32)	Note that this does not include WebSearch posts Read-only response field.
flaggedPosts	integer (int32)
totalSentiment	number (double)
webSearchPosts	integer (int32)
sanctionsSearchPosts	integer (int32)
hasAvailablePosts	boolean	Read-only response field.
isBackgroundCheckInProgress	boolean	Read-only response field.
preferencesProfileID	string (uuid)	The ID of the OrganizationPreferencesProfile used in background checks Nullable.
isEnabledForContinuousScreening	boolean	Boolean to indicate whether this subject is enabled for continuous screening
subscriberEnablingContinuousScreening	string (uuid)	Nullable.
continuousScreeningPreferences	OrganizationPreferencesProfile
continuousScreeningInterval	ContinuousScreeningInterval
continuousScreeningHourBucket	integer (int32)	Round-robin hour-of-day bucket (0-23) this subject’s Daily-interval continuous screening run is assigned to. Only set when ContinuousScreeningInterval is Daily; null for Monthly+ subjects and when continuous screening is disabled. Nullable.
continuousScreeningNotificationEmail	string	Nullable.
continuousScreeningLastCreditChargedAt	string (date-time)	The date/time when a credit was last charged for a continuous screening background check for this subject. Used to determine whether a credit should be charged when a new continuous screening check is initiated (a charge is made if this is null or more than 12 months ago). Nullable.
supplementaryDocumentBlobName	string	Nullable.
supplementaryDocumentFilename	string	Nullable.
supplementaryDocumentContentType	string	Nullable.
previousRunDate	string (date-time)	Nullable.
nextScreeningDate	string (date-time)	Nullable.
originalScreeningDate	string (date-time)	Nullable.
isAssignedToFerretlyAnalyst	boolean
dateAssignedToAnalyst	string (date-time)	Nullable.
assignedToAnalystAuditInfo	AuditInfo
assignedAnalystId	string (uuid)	Gets and sets the ID of the analyst assigned to this subject Nullable.
slaTimeInHours	integer (int32)	Gets or sets the number of hours that was used for calculating SLA expiration time. Nullable.
slaExpirationTime	string (date-time)	Gets and sets the date/time when the SLA expires. Nullable.
turnAroundTimeInHours	number (double)	Gets and sets the turn-around, in hours, for this subject. The calculation is performed differently for subjects assigned to an analyst than otherwise. Nullable.
ageOrDateOfBirth	string	Nullable.
isExternalApiSubject	boolean	Indicates whether the subject was created via the external API
externalSystemId	string	An identifier for the subject as it’s known to the external system Nullable.
isPostMigrationScheduled	boolean
areSubjectProfilesReviewed	boolean	Indicates whether the subject’s profiles have been reviewed by Analyst after search
runBGCheckAfterSearchIsFinished	boolean	If true, a background check will be automatically triggered after agentic search completes profile validation, provided the organization has no Analyst Assistance.
notes	string	Notes about this subject. Free-form text. Nullable.
lastUpdated	string (date-time)	Date/time of the last update to this subject Nullable. Read-only response field.
lastUpdatedBy	string	The name of the person who last updated this subject Nullable. Read-only response field.
lastUpdatedByEmail	string	The email address of the person who last updated this subject Nullable. Read-only response field.
lastUpdatedBySubscriberId	string (uuid)	The ID of the subscriber who last updated this subject Nullable. Read-only response field.
lastUpdatedAuditInfo	AuditInfo
platformSearchStatuses	array of PlatformSearchStatus	Nullable.
hasAgenticProfileSearch	boolean	True if an Agentic Profile Search has been initiated for this subject at least once. A credit is charged on first initiation, so this indicates that credit has been paid and the first background check can be run without an additional charge. Read-only response field.
postSummaryText	string	A string that represents AI-generated text that summarizes the subject’s most-recent flagged posts Nullable.
oceanPersonalityTraits	OceanPersonalityTraits
partitionKey	string	Nullable.
rowKey	string	Nullable.
timestamp	string (date-time)	Nullable.
eTag	ETag

handleList properties

Property	Type	Description
platform	string	Override the platform JSON output so that we get the correct casing. A value naming no known platform falls through as stored instead of becoming null, so it stays visible in an API response, and the setter writes the stored one, so this carries the inbound bind as well as the outbound. Nullable.
isSubjectProvided	boolean
verified	boolean
profileUrl	string	Nullable.
profilePicUrl	string	Nullable.
title	string	Nullable.
location	string	Nullable.
workplace	string	Nullable.
school	string	Nullable.
livesIn	string	Nullable.
from	string	Nullable.
livesInCoordinates	GeoLocation
fromCoordinates	GeoLocation
facebookStatus	string	Nullable.
socialMediaLinkedAccount	string	Nullable.
joined	string (date-time)
postCount	integer (int32)
followers	integer (int32)
following	integer (int32)
bio	string	Nullable.
status	HandleStatus
socialMediaProfileId	string	Nullable.
candidateProfileId	string (uuid)	The ID of the CandidateProfile that this handle is associated with. Nullable.
handleCreated	string (date-time)	Nullable.
validationStarted	string (date-time)	Nullable.
validationCompleted	string (date-time)	Nullable.
candidateProfile	CandidateProfileModel
handleSource	HandleSource
pronouns	string	Gets and sets any pronouns that are associated with this handle. Nullable.
handle	string	Nullable.
isPersonalProfile	boolean	Indicates whether this handle represents a personal profile, as opposed to a business or organization page.

subjectAddedAuditInfo properties

Property	Type	Description
occurredOn	string (date-time)	Date/time of the action Nullable.
subscriberName	string	The name of the person who performed the action Nullable.
subscriberEmail	string	The email address of the person who performed the action Nullable.
subscriberId	string (uuid)	The ID of the subscriber who performed the action Nullable.

coordinates properties

Property	Type	Description
latitude	number (double)
longitude	number (double)

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.

lastMarkedAsRedressedAuditInfo properties

Property	Type	Description
occurredOn	string (date-time)	Date/time of the action Nullable.
subscriberName	string	The name of the person who performed the action Nullable.
subscriberEmail	string	The email address of the person who performed the action Nullable.
subscriberId	string (uuid)	The ID of the subscriber who performed the action Nullable.

continuousScreeningPreferences properties

Property	Type	Description
id	string (uuid)	The unique identifier for this profile
profile_name	string	Nullable.
organizationId	string (uuid)	The organization to which this profile belongs
organizationName	string	The name of the organization Nullable.
isOrganizationDefaultProfile	boolean	Whether or not this profile is the organization default Read-only response field.
subscriberId	string (uuid)	If not null, this is a private profile Nullable.
isPrivateProfile	boolean	Read-only response field.
isActive	boolean	Support soft deletes of profiles
risk_categories	array of OrganizationRiskCategory	Nullable.
key_words	KeyWords
general_settings	GeneralSettings
disabledPlatforms	array of string	A list of social media platforms this profile has turned off. This list is exclusionary: if it is not empty, then handles on those platforms are not scraped and profiles found there are not attached automatically. If the list is empty, every platform applies. Nullable.
lastEdited	string (date-time)
lastEditedBy	string (uuid)	The ID of the Subscriber who last edited this profile. Null when the profile was last edited via the external API. Nullable.
lastEditedByName	string	The display name of the person or system that last edited this profile. Populated at write time. For human edits this is “{FirstName} {LastName}”; for external API edits this is the API client’s Owner name. Nullable.

assignedToAnalystAuditInfo properties

Property	Type	Description
occurredOn	string (date-time)	Date/time of the action Nullable.
subscriberName	string	The name of the person who performed the action Nullable.
subscriberEmail	string	The email address of the person who performed the action Nullable.
subscriberId	string (uuid)	The ID of the subscriber who performed the action Nullable.

lastUpdatedAuditInfo properties

Property	Type	Description
occurredOn	string (date-time)	Date/time of the action Nullable.
subscriberName	string	The name of the person who performed the action Nullable.
subscriberEmail	string	The email address of the person who performed the action Nullable.
subscriberId	string (uuid)	The ID of the subscriber who performed the action Nullable.

platformSearchStatuses properties

Property	Type	Description
platform	SearchPlatform
status	SearchStatusEnum
startedOn	string (date-time)	Nullable.
completedOn	string (date-time)	Nullable.
statusMessage	string	Nullable.
requestId	string (uuid)	Nullable.
timeoutMessageSequenceNumber	integer (int64)	Sequence number of the scheduled Service Bus timeout message. Set by SearchProgressHandler when the search receives a slot (Started status). Used by AgenticSearchCompletedHandler to cancel the timeout on completion. Null means no timeout has been scheduled yet (search is still queued). Nullable.

oceanPersonalityTraits properties

Property	Type	Description
openness	number (double)
conscientiousness	number (double)
extraversion	number (double)
agreeableness	number (double)
neuroticism	number (double)

Related guides

• Authentication
• With Analyst Assistance
• Without Analyst Assistance
• Errors and status codes