Create a subject

POST /api/Subjects

Use the configured organization workflow

For Analyst Assistance, use the analyst-assignment workflow and do not call initiateBackgroundCheck. Otherwise follow the workflow without Analyst Assistance. Debug examples below do not save subjects and deliberately leave analyst assignment disabled.

Authentication

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

A successful create returns a Subject with HTTP 200. Include subjectData.name. Debug mode skips the subject insert but is not a general sandbox; see the quickstart.

This request can change account configuration or stored data. Review the example values before running it.

Using the Subject Object’s Notes Field

Use subjectData.notes for optional free-form context for the reviewing analyst. Read it back as notes in the returned subject. This creation field is available in the updated backend model; confirm deployment support with Integrations if it is not yet listed in your live Swagger schema.

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 POST "https://api.ferretly.com/api/Subjects" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "subjectData": {
    "name": "Example Candidate",
    "city": "Example City",
    "country": "US",
    "email": "candidate@example.com",
    "linkedInUrl": "https://www.linkedin.com/in/your-candidate",
    "tags": [
      "integration-example"
    ],
    "notes": "Please review the supplied profile information."
  },
  "handles": [
    {
      "platform": "Twitter",
      "handle": "your_candidate",
      "profileUrl": "https://x.com/your_candidate"
    }
  ],
  "externalSystemId": "candidate-001",
  "assignToFerretlyAnalyst": false,
  "isDebug": true
}'

JavaScript

const response = await fetch("https://api.ferretly.com/api/Subjects", {
  "method": "POST",
  "headers": {
    "X-Api-Key": process.env.FERRETLY_API_KEY,
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "subjectData": {
    "name": "Example Candidate",
    "city": "Example City",
    "country": "US",
    "email": "candidate@example.com",
    "linkedInUrl": "https://www.linkedin.com/in/your-candidate",
    "tags": [
      "integration-example"
    ],
    "notes": "Please review the supplied profile information."
  },
  "handles": [
    {
      "platform": "Twitter",
      "handle": "your_candidate",
      "profileUrl": "https://x.com/your_candidate"
    }
  ],
  "externalSystemId": "candidate-001",
  "assignToFerretlyAnalyst": false,
  "isDebug": true
})
});
if (!response.ok) throw new Error("HTTP " + response.status);
console.log(await response.json());

Python

import os
import requests
import json

response = requests.request(
    "POST",
    "https://api.ferretly.com/api/Subjects",
    headers={"X-Api-Key":os.environ["FERRETLY_API_KEY"],"Accept":"application/json","Content-Type":"application/json"},
    json=json.loads("{\"subjectData\":{\"name\":\"Example Candidate\",\"city\":\"Example City\",\"country\":\"US\",\"email\":\"candidate@example.com\",\"linkedInUrl\":\"https://www.linkedin.com/in/your-candidate\",\"tags\":[\"integration-example\"],\"notes\":\"Please review the supplied profile information.\"},\"handles\":[{\"platform\":\"Twitter\",\"handle\":\"your_candidate\",\"profileUrl\":\"https://x.com/your_candidate\"}],\"externalSystemId\":\"candidate-001\",\"assignToFerretlyAnalyst\":false,\"isDebug\":true}"),
    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("POST"), "https://api.ferretly.com/api/Subjects");
request.Headers.Add("X-Api-Key", Environment.GetEnvironmentVariable("FERRETLY_API_KEY"));
request.Headers.Accept.ParseAdd("application/json");
request.Content = new StringContent("{\"subjectData\":{\"name\":\"Example Candidate\",\"city\":\"Example City\",\"country\":\"US\",\"email\":\"candidate@example.com\",\"linkedInUrl\":\"https://www.linkedin.com/in/your-candidate\",\"tags\":[\"integration-example\"],\"notes\":\"Please review the supplied profile information.\"},\"handles\":[{\"platform\":\"Twitter\",\"handle\":\"your_candidate\",\"profileUrl\":\"https://x.com/your_candidate\"}],\"externalSystemId\":\"candidate-001\",\"assignToFerretlyAnalyst\":false,\"isDebug\":true}", Encoding.UTF8, "application/json");
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Request body

Use application/json for JSON examples. The published operation also advertises these content types.

• application/json-patch+json: NewSubject
• application/json: NewSubject
• text/json: NewSubject
• application/*+json: NewSubject

Property	Type	Description
subjectData	EditSubject
handles	array of ApiSubjectHandle	Optional list of ApiSubjectHandle instances to add to the subject. Can be used instead of FacebookUrl, InstagramUrl, or TwitterUrl (for example) to add handles to a subject. Nullable.
assignToFerretlyAnalyst	boolean	Boolean indicating whether to assign the subject to a Ferretly analyst. The organization must have analyst assistance enabled.
externalSystemId	string	Optional but recommended identifier for the subject as it’s known in the source system. This value will be included in webhook notifications and can be used in query methods such as Nullable.
ownerEmail	string	Optional. If the subject should be assigned to a user other than the user associated with the API key, specifies that user’s email address. If the organization does not have a user with the specified email address, then the new subject will be assigned to the user associated with the API key. Nullable.
document	UploadSubjectDocument
isDebug	boolean	If true, the new subject will NOT BE ADDED to the database. This is useful for testing.
organizationId	string (uuid)	For internal use only. External API clients will not use this property. Organization ID to associate the subject with. If null, then an API key must be provided. Nullable.
preferencesProfile	string	(optional) The name or Guid id of the preference profile to use when creating the subject. If null or not specified, the ‘Default New Subject Profile’ for the registered subscriber (usually the org admin) will be used. Nullable.
continuousScreening	NewSubjectContinuousScreening

subjectData properties

Property	Type	Description
name	string	Required. The name of the subject. Nullable.
nickname	string	Optional. Another name/alias property for the subject Nullable.
profilePicUrl	string	Optional. A profile picture URL for the subject. Nullable.
address	string	Optional. The street address of the subject. Nullable.
city	string	Optional. The name of the city where the subject lives. Nullable.
state	string	Optional. The name of the state name the subject lives. Nullable.
country	string	Optional. The name of the country where the subject lives. Nullable.
ageOrDateOfBirth	string	Optional. The age or birth date of the subject. Nullable.
email	string	Optional. The email address of the subject. Note that this will not be automatically checked for validity. Nullable.
highSchool	string	Optional. The name of the high school the subject attended. Nullable.
college	string	Optional. The name of the college the subject attended. Nullable.
company	string	Optional. The name of the company the subject works for. Nullable.
phone	string	Optional. The phone number of the subject. Note that this will not be automatically checked for validity. Nullable.
twitterUrl	string	Optional. The URL of the subject’s Twitter profile. Nullable.
facebookUrl	string	Optional. The URL of the subject’s Facebook profile. Nullable.
instagramUrl	string	Optional. The URL of the subject’s Instagram profile. Nullable.
linkedInUrl	string	Optional. The URL of the subject’s LinkedIn profile. Nullable.
tiktokUrl	string	Optional. The URL of the subject’s TikTok profile. Nullable.
redditUrl	string	Optional. The URL of the subject’s Reddit profile. Nullable.
pinterestUrl	string	Optional. The URL of the subject’s Pinterest profile. Nullable.
youtubeUrl	string	Optional. The URL of the subject’s YouTube channel. All four channel URL forms are accepted: a handle ({/@name}), a channel id ({/channel/UC…}), and the legacy {/c/name} and {/user/name} forms. The identifier is stored with its prefix, because the forms are not interchangeable and may resolve to different channels. Nullable.
tags	array of string	Optional. A set of tags to associate with the subject. Nullable.
notes	string	Optional. Free-form notes about the subject, including context for the reviewing analyst. Notes can be read back from Subject.notes and edited in the Ferretly app. Nullable.

handles properties

Property	Type	Description
profilePicUrl	string	Nullable.
title	string	The name of the subject as it appears on the social media platform. Nullable.
location	string	Nullable.
workplace	string	Nullable.
school	string	Nullable.
livesIn	string	Nullable.
from	string	Nullable.
facebookStatus	string	Nullable.
socialMediaLinkedAccount	string	Nullable.
joined	string (date-time)	Nullable.
postCount	integer (int32)	Nullable.
followers	integer (int32)	Nullable.
following	integer (int32)	Nullable.
bio	string	Nullable.
platform	string	Nullable.
handle	string	Nullable.
profileUrl	string	The direct URL to the profile on the social media platform. Nullable.
isPersonalProfile	boolean	Indicates whether this handle represents a personal profile, as opposed to a business or organization page.

document properties

Property	Type	Description
filename	string	Required name for the document to be uploaded Nullable.
contentType	string	Required content type for the document to be uploaded Nullable.
imageData	string (byte)	Required base64-encoded content for the document to be uploaded Nullable.

continuousScreening properties

Property	Type	Description
isEnabled	boolean	Whether continuous screening should be enabled for this subject.
interval	ContinuousScreeningInterval
notificationEmail	string (email)	Optional email address to notify when a continuous screening background check completes. Nullable.

Responses

200

Created

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

400

Requested Analyst Support but organization does not have Analyst Support

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