{
"openapi": "3.0.1",
"info": {
"title": "Ferretly External API",
"description": "The Ferretly External API allows integration partners to create and manage subjects, initiate background screenings, and retrieve screening results programmatically. Includes screening status callback definitions.",
"contact": {
"name": "Ferretly Integrations",
"email": "integrations@ferretly.com"
},
"version": "v1"
},
"servers": [
{
"url": "https://api.ferretly.com"
}
],
"paths": {
"/api/ApiClient": {
"get": {
"tags": [
"ApiClient"
],
"summary": "Get information about the API client associated with the API key found in the request header",
"description": "Using the API key found in the request header, return information about the API client",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ApiClient"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiClient"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ApiClient"
}
}
}
}
}
}
},
"/api/ApiClient/updateWebHook": {
"post": {
"tags": [
"ApiClient"
],
"summary": "Update the web hook url associated with the API client. This is the URL which will receive callbacks from Ferretly",
"requestBody": {
"description": "The new URL to use.",
"content": {
"application/json-patch+json": {
"schema": {
"type": "string"
}
},
"application/json": {
"schema": {
"type": "string"
}
},
"text/json": {
"schema": {
"type": "string"
}
},
"application/*+json": {
"schema": {
"type": "string"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ApiClient"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiClient"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ApiClient"
}
}
}
}
},
"callbacks": {
"statusChanged": {
"$ref": "#/components/callbacks/FerretlyStatusChange"
}
}
}
},
"/api/ApiClient/refreshApiKey": {
"get": {
"tags": [
"ApiClient"
],
"summary": "Refresh the API key associated with an API client.",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ApiClientWithApiKey"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiClientWithApiKey"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ApiClientWithApiKey"
}
}
}
}
}
}
},
"/api/ApiClient/getOrganization": {
"get": {
"tags": [
"ApiClient"
],
"summary": "Get the Ferretly Data.DTO.Organization related to the API key",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Organization"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/Organization"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Organization"
}
}
}
}
}
}
},
"/api/ApiClient/updateClientSpecificProperties": {
"post": {
"tags": [
"ApiClient"
],
"summary": "Update the Data.Models.ExternalAPI.ExternalAPIClientEntity.ClientSpecificProperties associated with the API client.",
"requestBody": {
"description": "The new value to store as the Data.Models.ExternalAPI.ExternalAPIClientEntity.ClientSpecificProperties",
"content": {
"application/json-patch+json": {
"schema": {
"type": "string"
}
},
"application/json": {
"schema": {
"type": "string"
}
},
"text/json": {
"schema": {
"type": "string"
}
},
"application/*+json": {
"schema": {
"type": "string"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ApiClient"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiClient"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ApiClient"
}
}
}
}
}
}
},
"/api/ApiClient/updateTechnicalContact": {
"post": {
"tags": [
"ApiClient"
],
"summary": "Update the technical contact email address for the API client.",
"requestBody": {
"description": "The new technical contact email address.",
"content": {
"application/json-patch+json": {
"schema": {
"type": "string"
}
},
"application/json": {
"schema": {
"type": "string"
}
},
"text/json": {
"schema": {
"type": "string"
}
},
"application/*+json": {
"schema": {
"type": "string"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/ApiClient"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiClient"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/ApiClient"
}
}
}
}
}
}
},
"/api/Health/settings": {
"get": {
"tags": [
"Health"
],
"summary": "Basic API health and settings",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/AppSettings"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppSettings"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/AppSettings"
}
}
}
},
"401": {
"description": "Not logged in"
}
},
"security": []
}
},
"/api/PreferenceProfiles/behavior-categories": {
"get": {
"tags": [
"PreferenceProfiles"
],
"summary": "Gets the default set of behavior category items.",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PreferenceProfileBehaviorCategory"
}
}
},
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PreferenceProfileBehaviorCategory"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PreferenceProfileBehaviorCategory"
}
}
}
}
}
}
}
},
"/api/PreferenceProfiles": {
"get": {
"tags": [
"PreferenceProfiles"
],
"summary": "Gets the preference profiles for the authenticated client's organization.",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PreferenceProfile"
}
}
},
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PreferenceProfile"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PreferenceProfile"
}
}
}
}
},
"401": {
"description": "The subscriber or organization identifier is missing from the request credentials."
}
}
},
"post": {
"tags": [
"PreferenceProfiles"
],
"summary": "Creates an org-wide preference profile for the authenticated client's organization.",
"description": "Preference profile creation requires the 'AllowPreferenceProfileUpdate' setting to be enabled for your organization by Ferretly.",
"requestBody": {
"content": {
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/PreferenceProfileUpsert"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/PreferenceProfileUpsert"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/PreferenceProfileUpsert"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/PreferenceProfileUpsert"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/OrganizationPreferencesProfile"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationPreferencesProfile"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationPreferencesProfile"
}
}
}
},
"400": {
"description": "The request body is null; one or more behavior categories are not valid; the profile name is already in use; 'Email me' is enabled but no notification address is provided; or the notification email address is invalid."
},
"401": {
"description": "The subscriber or organization identifier is missing from the request credentials."
},
"403": {
"description": "The preference profile creation endpoint is disabled by configuration, or the organization is not allowed to create preference profiles."
},
"404": {
"description": "No subscriber was found for the provided identifiers."
}
}
}
},
"/api/PreferenceProfiles/{id}": {
"get": {
"tags": [
"PreferenceProfiles"
],
"summary": "Gets a single preference profile by ID.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/OrganizationPreferencesProfile"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationPreferencesProfile"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationPreferencesProfile"
}
}
}
},
"401": {
"description": "The subscriber or organization identifier is missing from the request credentials."
},
"403": {
"description": "The profile does not belong to the authenticated client's organization."
},
"404": {
"description": "No preference profile was found with the specified ID."
}
}
},
"put": {
"tags": [
"PreferenceProfiles"
],
"summary": "Updates an organization-wide preference profile for the authenticated client's organization.",
"description": "Preference profile updates require the 'AllowPreferenceProfileUpdate' setting to be enabled for your organization by Ferretly.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"requestBody": {
"content": {
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/PreferenceProfileUpsert"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/PreferenceProfileUpsert"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/PreferenceProfileUpsert"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/PreferenceProfileUpsert"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/OrganizationPreferencesProfile"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationPreferencesProfile"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationPreferencesProfile"
}
}
}
},
"400": {
"description": "The request body is null; one or more behavior categories are not valid; 'Email me' is enabled but no notification address is provided; the notification email address is invalid; the organization default profile is being renamed; the profile is associated with a specific subscriber; the profile ID in the request body does not match the ID in the route."
},
"401": {
"description": "The subscriber or organization identifier is missing from the request credentials."
},
"403": {
"description": "The profile being updated does not belong to the authenticated client's organization, the update endpoint is disabled by configuration, or the organization is not allowed to update preference profiles."
},
"404": {
"description": "No preference profile was found with the specified ID."
}
}
},
"delete": {
"tags": [
"PreferenceProfiles"
],
"summary": "Soft-deletes a preference profile for the authenticated client's organization.",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/OrganizationPreferencesProfile"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationPreferencesProfile"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationPreferencesProfile"
}
}
}
},
"400": {
"description": "The specified profile is the organization-wide default profile, which cannot be deleted."
},
"401": {
"description": "The subscriber or organization identifier is missing from the request credentials."
},
"403": {
"description": "The specified profile does not belong to the authenticated client's organization."
},
"404": {
"description": "No preference profile was found with the specified ID."
}
}
}
},
"/api/Subjects": {
"get": {
"tags": [
"Subjects"
],
"summary": "Get a list of all of the subscriber's subjects",
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Subject"
}
}
},
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Subject"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Subject"
}
}
}
}
}
}
},
"post": {
"tags": [
"Subjects"
],
"summary": "Create a new subject",
"requestBody": {
"description": "The new subject",
"content": {
"application/json-patch+json": {
"schema": {
"$ref": "#/components/schemas/NewSubject"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/NewSubject"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/NewSubject"
}
},
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/NewSubject"
}
}
}
},
"responses": {
"200": {
"description": "Created",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Subject"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/Subject"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Subject"
}
}
}
},
"400": {
"description": "Requested Analyst Support but organization does not have Analyst Support"
}
}
}
},
"/api/Subjects/{subjectId}": {
"get": {
"tags": [
"Subjects"
],
"summary": "Get a particular subject",
"parameters": [
{
"name": "subjectId",
"in": "path",
"description": "",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Subject"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/Subject"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Subject"
}
}
}
},
"404": {
"description": "Subject was not found"
}
}
}
},
"/api/Subjects/getByExternalId/{externalId}": {
"get": {
"tags": [
"Subjects"
],
"summary": "Get a particular subject by external id value",
"description": "If there are multiple subjects having the specified externalId value, the \"first\" will be returned",
"parameters": [
{
"name": "externalId",
"in": "path",
"description": "",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Subject"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/Subject"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Subject"
}
}
}
},
"404": {
"description": "Subject was not found"
}
}
}
},
"/api/Subjects/{subjectId}/screeningstatus": {
"get": {
"tags": [
"Subjects"
],
"summary": "Get status of background screen for the requested subject",
"parameters": [
{
"name": "subjectId",
"in": "path",
"description": "",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/BackgroundCheckStatus"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BackgroundCheckStatus"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BackgroundCheckStatus"
}
}
}
}
}
}
},
"/api/Subjects/{externalId}/screeningStatusByExternalId": {
"get": {
"tags": [
"Subjects"
],
"summary": "Get status of background screen for the requested subject",
"parameters": [
{
"name": "externalId",
"in": "path",
"description": "The \"external\" id value for the subject. This value is specified by the API client when the subject is created.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/BackgroundCheckStatus"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BackgroundCheckStatus"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BackgroundCheckStatus"
}
}
}
}
}
}
},
"/api/Subjects/{subjectId}/backgroundCheckResults": {
"get": {
"tags": [
"Subjects"
],
"summary": "Get results from most recently-completed background screen for the requested subject",
"parameters": [
{
"name": "subjectId",
"in": "path",
"description": "",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/BackgroundCheckResults"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BackgroundCheckResults"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BackgroundCheckResults"
}
}
}
}
}
}
},
"/api/Subjects/getByExternalId/{externalId}/backgroundCheckResults": {
"get": {
"tags": [
"Subjects"
],
"summary": "Get results from most recently-completed background screen for the requested subject",
"parameters": [
{
"name": "externalId",
"in": "path",
"description": "",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/BackgroundCheckResults"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BackgroundCheckResults"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BackgroundCheckResults"
}
}
}
},
"400": {
"description": "Something was invalid about the request: subject does not have a completed background check; subject currently has background check in-progress",
"content": {
"text/plain": {
"schema": {
"type": "string"
}
},
"application/json": {
"schema": {
"type": "string"
}
},
"text/json": {
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "Subject was not found"
}
}
}
},
"/api/Subjects/{subjectId}/initiateBackgroundCheck": {
"get": {
"tags": [
"Subjects"
],
"summary": "Initiate the social media screening portion of a background check for the specified subject. If your organization has Analyst Assistance, it's likely that you should not be using this endpoint. :)",
"parameters": [
{
"name": "subjectId",
"in": "path",
"description": "",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Successfully attempted to start background check",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/BackgroundCheckStatus"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/BackgroundCheckStatus"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/BackgroundCheckStatus"
}
}
}
},
"400": {
"description": "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."
}
}
}
},
"/api/Subjects/{subjectId}/filteredPosts": {
"get": {
"tags": [
"Subjects"
],
"summary": "Get filtered list of posts for the specified subject",
"parameters": [
{
"name": "subjectId",
"in": "path",
"description": "",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "typeFilter",
"in": "query",
"description": "",
"schema": {
"$ref": "#/components/schemas/PostTypeFilter"
}
},
{
"name": "dateFilter",
"in": "query",
"description": "",
"schema": {
"$ref": "#/components/schemas/PostDateFilter"
}
}
],
"responses": {
"200": {
"description": "List of posts",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Post"
}
}
},
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Post"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Post"
}
}
}
}
},
"400": {
"description": "Subject does not exist, is not valid for the API client."
}
}
}
},
"/api/Subjects/{externalId}/filteredPostsByExternalId": {
"get": {
"tags": [
"Subjects"
],
"summary": "Get filtered list of posts for the specified subject",
"parameters": [
{
"name": "externalId",
"in": "path",
"description": "",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "typeFilter",
"in": "query",
"description": "",
"schema": {
"$ref": "#/components/schemas/PostTypeFilter"
}
},
{
"name": "dateFilter",
"in": "query",
"description": "",
"schema": {
"$ref": "#/components/schemas/PostDateFilter"
}
}
],
"responses": {
"200": {
"description": "List of posts",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Post"
}
}
},
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Post"
}
}
},
"text/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Post"
}
}
}
}
},
"400": {
"description": "Subject does not exist, is not valid for the API client."
}
}
}
},
"/api/Subjects/{subjectId}/downloadBackgroundReport": {
"get": {
"tags": [
"Subjects"
],
"summary": "Download the latest background report for the requested subject",
"parameters": [
{
"name": "subjectId",
"in": "path",
"description": "",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/octet-stream": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"description": "The subject does not have a current background report, or it is being regenerated"
},
"404": {
"description": "Subject not found, or report file could not be located in Blob Storage"
}
}
}
}
},
"components": {
"schemas": {
"AffiliateInfo": {
"type": "object",
"properties": {
"_id": {
"type": "string",
"format": "uuid"
},
"_owner": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"nullable": true
},
"status": {
"type": "string",
"nullable": true
},
"_createdDate": {
"type": "string",
"format": "date-time"
},
"_updatedDate": {
"type": "string",
"format": "date-time"
},
"companyName": {
"type": "string",
"nullable": true
},
"websiteAddress": {
"type": "string",
"nullable": true
},
"whitelabel": {
"type": "boolean"
},
"logo": {
"type": "string",
"nullable": true
},
"companyAddress": {
"type": "string",
"nullable": true
},
"companyAddress2": {
"type": "string",
"nullable": true
},
"companyCity": {
"type": "string",
"nullable": true
},
"companyPostalCode": {
"type": "string",
"nullable": true
},
"companyState": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"ApiClient": {
"type": "object",
"properties": {
"subscriberId": {
"type": "string",
"description": "The id of the Ferretly user associated with the API client key",
"format": "uuid"
},
"organizationId": {
"type": "string",
"description": "The id of the Ferretly organization associated with the API client key",
"format": "uuid"
},
"owner": {
"type": "string",
"description": "Name of the API client key owner",
"nullable": true
},
"permissions": {
"type": "string",
"description": "Comma-separated list of permissions associated with the API client",
"nullable": true
},
"statusUpdateCallbackUrl": {
"type": "string",
"description": "Webhook URL",
"nullable": true
},
"clientSpecificProperties": {
"type": "string",
"description": "A place to store additional, generic properties about the API Client",
"nullable": true
},
"technicalContactEmail": {
"type": "string",
"description": "Email address of the technical contact for this API client organization.",
"nullable": true
},
"allowPreferenceProfileUpdate": {
"type": "boolean",
"description": "Gets or sets a value indicating whether this API client is allowed to update preference profiles."
}
},
"additionalProperties": false,
"description": "Information about the API client"
},
"ApiClientWithApiKey": {
"type": "object",
"properties": {
"apiClient": {
"$ref": "#/components/schemas/ApiClient"
},
"apiKey": {
"type": "string",
"description": "The API Key for this client",
"nullable": true
}
},
"additionalProperties": false,
"description": "Class used when wanting to return an Data.Models.ExternalAPI.ApiClientWithApiKey.ApiClient and its associated "
},
"ApiSubjectHandle": {
"type": "object",
"properties": {
"profilePicUrl": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"description": "The name of the subject as it appears on the social media platform.",
"nullable": true
},
"location": {
"type": "string",
"nullable": true
},
"workplace": {
"type": "string",
"nullable": true
},
"school": {
"type": "string",
"nullable": true
},
"livesIn": {
"type": "string",
"nullable": true
},
"from": {
"type": "string",
"nullable": true
},
"facebookStatus": {
"type": "string",
"nullable": true
},
"socialMediaLinkedAccount": {
"type": "string",
"nullable": true
},
"joined": {
"type": "string",
"format": "date-time",
"nullable": true
},
"postCount": {
"type": "integer",
"format": "int32",
"nullable": true
},
"followers": {
"type": "integer",
"format": "int32",
"nullable": true
},
"following": {
"type": "integer",
"format": "int32",
"nullable": true
},
"bio": {
"type": "string",
"nullable": true
},
"platform": {
"type": "string",
"nullable": true
},
"handle": {
"type": "string",
"nullable": true
},
"profileUrl": {
"type": "string",
"description": "The direct URL to the profile on the social media platform.",
"nullable": true,
"example": "https://www.linkedin.com/in/johndoe"
},
"isPersonalProfile": {
"type": "boolean",
"description": "Indicates whether this handle represents a personal profile, as opposed to a business or organization page.",
"example": true
}
},
"additionalProperties": false
},
"AppSettings": {
"type": "object",
"properties": {
"storageAccount": {
"type": "string",
"nullable": true
},
"storageKey": {
"type": "string",
"nullable": true
},
"ferretlyAnalystEmailAddress": {
"type": "string",
"nullable": true
},
"subjectAssignedToYouTemplateId": {
"type": "string",
"nullable": true
},
"emptyProfileImageUrl": {
"type": "string",
"nullable": true
},
"sendGridApiKey": {
"type": "string",
"nullable": true
},
"applicationUrl": {
"type": "string",
"nullable": true
},
"platform": {
"$ref": "#/components/schemas/Platform"
},
"isDevelopmentEnvironment": {
"type": "boolean"
},
"fetcherManagerUrl": {
"type": "string",
"nullable": true
},
"profilePicBaseUrl": {
"type": "string",
"nullable": true
},
"profilePicsContainer": {
"type": "string",
"nullable": true
},
"elasticSearchSettings": {
"$ref": "#/components/schemas/IElasticSearchSettings"
},
"elasticSearchPostSettings": {
"$ref": "#/components/schemas/IElasticSearchSettings"
},
"workerQueueTable": {
"type": "string",
"nullable": true
},
"organizationPreferencesIndexName": {
"type": "string",
"nullable": true
},
"tableNames": {
"$ref": "#/components/schemas/ITableNames"
},
"reportsBlobStorageUrl": {
"type": "string",
"nullable": true
},
"backgroundReportBlobContainer": {
"type": "string",
"nullable": true
},
"supplementaryDocumentBlobStorageUrl": {
"type": "string",
"nullable": true
},
"externalApiBaseUrl": {
"type": "string",
"nullable": true
},
"replyToEmailAddress": {
"type": "string",
"nullable": true
},
"directApiKeyCreatedTemplateId": {
"type": "string",
"description": "SendGrid template ID for the email sent to the org admin and technical contact\r\nwhen a new \"Direct\" integration type API client is created.",
"nullable": true
},
"oneTimeSecretApiUrl": {
"type": "string",
"description": "Base URL for the onetimesecret.com share API, used to wrap a newly-created API key\r\nin a one-time-view link before emailing it.",
"nullable": true
},
"oneTimeSecretUsername": {
"type": "string",
"nullable": true
},
"oneTimeSecretApiKey": {
"type": "string",
"nullable": true
},
"oneTimeSecretTtlSeconds": {
"type": "integer",
"description": "How long (in seconds) a onetimesecret.com link remains valid before it expires unread.",
"format": "int32"
}
},
"additionalProperties": false
},
"AuditInfo": {
"type": "object",
"properties": {
"occurredOn": {
"type": "string",
"description": "Date/time of the action",
"format": "date-time",
"nullable": true
},
"subscriberName": {
"type": "string",
"description": "The name of the person who performed the action",
"nullable": true
},
"subscriberEmail": {
"type": "string",
"description": "The email address of the person who performed the action",
"nullable": true
},
"subscriberId": {
"type": "string",
"description": "The ID of the subscriber who performed the action",
"format": "uuid",
"nullable": true
}
},
"additionalProperties": false
},
"BackgroundCheckResults": {
"type": "object",
"properties": {
"initiated": {
"type": "string",
"description": "When the background check was initiated",
"format": "date-time"
},
"subjectId": {
"type": "string",
"description": "The Ferretly subject ID",
"format": "uuid"
},
"subjectExternalSystemId": {
"type": "string",
"description": "The subject's external system ID (if provided).",
"nullable": true,
"example": "ferretly_12345"
},
"riskMakeups": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RiskMakeup"
},
"description": "Risk makeups: count of posts flagged for each risk",
"nullable": true,
"readOnly": true
},
"channelVolumes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChannelVolume"
},
"description": "Count of posts found per-platform",
"nullable": true
},
"flaggedPosts": {
"type": "integer",
"description": "Count of flagged posts",
"format": "int32",
"example": 33
},
"flagCount": {
"type": "integer",
"description": "Total number of flags found in Data.Models.ExternalAPI.BackgroundCheckResults.RiskMakeups. Not necessarily the same\r\nvalue as Data.Models.ExternalAPI.BackgroundCheckResults.FlaggedPosts",
"format": "int32",
"example": 14
},
"totalPosts": {
"type": "integer",
"description": "Count of posts found",
"format": "int32",
"readOnly": true,
"example": 123
},
"webSearchPosts": {
"type": "integer",
"description": "Count of web search posts found",
"format": "int32",
"example": 12
},
"score": {
"type": "integer",
"description": "Calculated score",
"format": "int32",
"example": 775
},
"totalSentiment": {
"type": "number",
"description": "The total sentiment (sum of sentiment from all posts)",
"format": "double",
"example": 12.234
},
"finishedScraping": {
"type": "string",
"description": "When the post fetcher completed fetching the last post",
"format": "date-time",
"nullable": true
},
"runStatus": {
"$ref": "#/components/schemas/RunStatusEnum"
},
"isRedressed": {
"type": "boolean",
"description": "A boolean indicating whether this subject has been \"marked as redressed\""
},
"lastMarkAsRedressedOn": {
"type": "string",
"description": "The most recent time the subject was \"marked as redressed\". Will be null if the subject has\r\nnot been \"marked as redressed\"",
"format": "date-time",
"nullable": true
},
"postSummaryText": {
"type": "string",
"description": "A string that represents AI-generated text that summarizes the subject's most-recent flagged posts",
"nullable": true
}
},
"additionalProperties": false
},
"BackgroundCheckStatus": {
"enum": [
"None",
"InQueue",
"InProgress",
"Redressing",
"Complete",
"Error",
"Redressed"
],
"type": "string"
},
"BehaviorSource": {
"enum": [
0,
1,
2,
3
],
"type": "integer",
"format": "int32"
},
"CandidateProfileModel": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"subjectId": {
"type": "string",
"format": "uuid"
},
"platform": {
"enum": [
"Facebook",
"Instagram",
"Twitter",
"LinkedIn",
"TikTok",
"Reddit",
"Pinterest",
"YouTube"
],
"type": "string"
},
"source": {
"$ref": "#/components/schemas/CandidateProfileSource"
},
"handle": {
"type": "string",
"nullable": true
},
"cityStateCountry": {
"type": "string",
"nullable": true
},
"ageDOB": {
"type": "string",
"nullable": true
},
"bio": {
"type": "string",
"nullable": true
},
"profilePhotoUrl": {
"type": "string",
"nullable": true
},
"profileUrl": {
"type": "string",
"nullable": true
},
"validationSuccessful": {
"type": "boolean",
"nullable": true
},
"isUsedInSubject": {
"type": "boolean"
},
"isValidated": {
"type": "boolean"
},
"isPersonalProfile": {
"type": "boolean"
},
"profileImageSimilarity": {
"type": "number",
"format": "float"
},
"profileImageMatchType": {
"$ref": "#/components/schemas/ImageMatchType"
},
"confidence": {
"type": "number",
"format": "float"
},
"fullNames": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"addresses": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"emails": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"companies": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"colleges": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"highSchools": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"phones": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"otherNames": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"identifiers": {
"$ref": "#/components/schemas/ProfileIdentifiers"
},
"location": {
"$ref": "#/components/schemas/Coordinates"
},
"searchIteration": {
"type": "string",
"description": "Represents a search iteration step where this candidate came from. Null for non-search (validation) candidates",
"nullable": true
},
"socialMediaProfileId": {
"type": "string",
"description": "Represents a unique candidate id provided by platform",
"nullable": true
},
"isNotAvailableForHandle": {
"type": "boolean",
"description": "A Boolean indicating whether this profile is not available for use as\r\na subject handle. This is typically used for profiles that are\r\nfound to be duplicates or otherwise unsuitable for handles."
},
"reasoning": {
"type": "string",
"description": "LLM reasoning",
"nullable": true
}
},
"additionalProperties": false
},
"CandidateProfileSource": {
"enum": [
0,
1,
2,
3,
4,
5,
6
],
"type": "integer",
"format": "int32"
},
"ChannelVolume": {
"type": "object",
"properties": {
"channelName": {
"type": "string",
"nullable": true
},
"count": {
"type": "integer",
"format": "int32"
},
"flaggedPosts": {
"type": "integer",
"format": "int32",
"nullable": true
}
},
"additionalProperties": false
},
"ContinuousScreeningInterval": {
"enum": [
"None",
"Monthly",
"SemiAnnual",
"Annual",
"Quarterly",
"Daily"
],
"type": "string"
},
"Coordinates": {
"type": "object",
"properties": {
"latitude": {
"type": "number",
"format": "double"
},
"longitude": {
"type": "number",
"format": "double"
}
},
"additionalProperties": false
},
"DataRetentionPeriod": {
"enum": [
0,
1
],
"type": "integer",
"format": "int32"
},
"EditSubject": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Required. The name of the subject.",
"nullable": true,
"example": "John Smith"
},
"nickname": {
"type": "string",
"description": "Optional. Another name/alias property for the subject",
"nullable": true,
"example": "William"
},
"profilePicUrl": {
"type": "string",
"description": "Optional. A profile picture URL for the subject.",
"nullable": true,
"example": "https://pbs.twimg.com/profile_images/1674815862879178752/nTGMV1Eo_400x400.jpg"
},
"address": {
"type": "string",
"description": "Optional. The street address of the subject.",
"nullable": true,
"example": "123 Main St."
},
"city": {
"type": "string",
"description": "Optional. The name of the city where the subject lives.",
"nullable": true,
"example": "San Francisco"
},
"state": {
"type": "string",
"description": "Optional. The name of the state name the subject lives.",
"nullable": true
},
"country": {
"type": "string",
"description": "Optional. The name of the country where the subject lives.",
"nullable": true,
"example": "United States"
},
"ageOrDateOfBirth": {
"type": "string",
"description": "Optional. The age or birth date of the subject.",
"nullable": true,
"example": "1995-01-01"
},
"email": {
"type": "string",
"description": "Optional. The email address of the subject. Note that this will not be automatically checked for validity.",
"nullable": true,
"example": "john.smith@gmail.com"
},
"highSchool": {
"type": "string",
"description": "Optional. The name of the high school the subject attended.",
"nullable": true,
"example": "San Francisco High School"
},
"college": {
"type": "string",
"description": "Optional. The name of the college the subject attended.",
"nullable": true,
"example": "San Francisco State University"
},
"company": {
"type": "string",
"description": "Optional. The name of the company the subject works for.",
"nullable": true,
"example": "International Widgets, Inc."
},
"phone": {
"type": "string",
"description": "Optional. The phone number of the subject. Note that this will not be automatically checked for validity.",
"nullable": true,
"example": "415-555-1234"
},
"twitterUrl": {
"type": "string",
"description": "Optional. The URL of the subject's Twitter profile.",
"nullable": true,
"example": "https://twitter.com/billgates"
},
"facebookUrl": {
"type": "string",
"description": "Optional. The URL of the subject's Facebook profile.",
"nullable": true,
"example": "https://www.facebook.com/billgates"
},
"instagramUrl": {
"type": "string",
"description": "Optional. The URL of the subject's Instagram profile.",
"nullable": true,
"example": "https://www.instagram.com/billgates"
},
"linkedInUrl": {
"type": "string",
"description": "Optional. The URL of the subject's LinkedIn profile.",
"nullable": true,
"example": "https://www.linkedin.com/in/billgates"
},
"tiktokUrl": {
"type": "string",
"description": "Optional. The URL of the subject's TikTok profile.",
"nullable": true,
"example": "https://www.tiktok.com/@billgates"
},
"redditUrl": {
"type": "string",
"description": "Optional. The URL of the subject's Reddit profile.",
"nullable": true,
"example": "https://www.reddit.com/user/billgates"
},
"pinterestUrl": {
"type": "string",
"description": "Optional. The URL of the subject's Pinterest profile.",
"nullable": true,
"example": "https://www.pinterest.com/billgates"
},
"youtubeUrl": {
"type": "string",
"description": "Optional. The URL of the subject's YouTube channel. All four channel URL forms are accepted:\r\na handle ({/@name}), a channel id ({/channel/UC...}), and the legacy\r\n{/c/name} and {/user/name} forms. The identifier is stored with its prefix, because\r\nthe forms are not interchangeable and may resolve to different channels.",
"nullable": true,
"example": "https://www.youtube.com/@billgates"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional. A set of tags to associate with the subject.",
"nullable": true
},
"notes": {
"type": "string",
"nullable": true,
"description": "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."
}
},
"additionalProperties": false
},
"ETag": {
"type": "object",
"additionalProperties": false
},
"FlagInfo": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"labelName": {
"type": "string",
"nullable": true
},
"flagLevel": {
"type": "number",
"description": "Value is between 0 and 1 and is assumed to be a percentage value",
"format": "double"
},
"keywordFlagLabel": {
"type": "string",
"nullable": true
},
"keywordFlagType": {
"$ref": "#/components/schemas/KeywordType"
},
"behaviorSource": {
"$ref": "#/components/schemas/BehaviorSource"
},
"riskType": {
"$ref": "#/components/schemas/RiskType"
}
},
"additionalProperties": false
},
"GeneralSettings": {
"type": "object",
"properties": {
"email_me": {
"type": "boolean",
"description": "Indicates whether to send background check status change emails to the\r\nuser specified in Data.Models.Preferences.GeneralSettings.NotificationEmailAddress"
},
"notificationEmailAddress": {
"type": "string",
"nullable": true
},
"email_subject_owner_on_completion": {
"type": "boolean",
"description": "When true, causes emails to be\r\nsent only upon mark redressed for organizations with\r\nAnalyst Assistance, or upon run complete w/o Analyst Assistance."
},
"is_flagged": {
"type": "boolean"
},
"is_negative": {
"type": "boolean"
},
"is_positive": {
"type": "boolean"
},
"hide_logos": {
"type": "boolean"
},
"includeHelpPagesOnBackgroundReport": {
"type": "boolean"
},
"includeHyperlinksInReports": {
"type": "boolean"
},
"include_web_news_posts": {
"type": "boolean",
"description": "If true, a news/web search will be performed for the\r\nsubject, and results will be added as new posts"
},
"minimum_web_post_confidence_level": {
"type": "string",
"description": "String representation of Data.Models.Preferences.GeneralSettings.MinimumWebPostConfidenceLevel, because of\r\ninconsistency in the way enums are serialized in the API",
"nullable": true
},
"include_fcra": {
"type": "boolean",
"description": "Boolean to indicate whether FCRA warnings and disclaimers are shown, and to control number of years of posts to fetch"
},
"isFCRAYearsOverriden": {
"type": "boolean",
"description": "When set to true, allows for Data.Models.Preferences.GeneralSettings.AlternativeNumberOfYearsForPosts to specify number of years of posts to fetch"
},
"alternativeNumberOfYearsForPosts": {
"type": "integer",
"description": "If Data.Models.Preferences.GeneralSettings.IsFCRAYearsOverriden is true, number of years of posts to retrieve",
"format": "int32",
"nullable": true
},
"anonymizeProfilePictureInReports": {
"type": "boolean"
},
"includePostInsightsInReports": {
"type": "boolean"
},
"basicInsightsIsOnePage": {
"type": "boolean"
},
"report_background_color": {
"type": "string",
"description": "Background color for the report.",
"nullable": true
},
"hideSentimentOnReports": {
"type": "boolean",
"description": "If true then don't display sentiment icon on posts pages in reports"
},
"useAlternateDisclaimerText": {
"type": "boolean",
"description": "A boolean to indicate whether the organization's \"Alternate Disclaimer Text\" should be used in the report"
},
"showZeroScoreWhenNoHandles": {
"type": "boolean",
"description": "\"Show Score as 0 when no handles\""
},
"excludeHandleBiosOnCoverPage": {
"type": "boolean",
"description": "\"Exclude Handle Bio's on cover page\""
},
"excludeScoreOnPostsInsights": {
"type": "boolean",
"description": "\"Exclude score on post insights\""
},
"isPrinterFriendlyReport": {
"type": "boolean",
"description": "Boolean to indicate that the report style should be \"printer friendly\""
},
"reportAnalyticsSections": {
"$ref": "#/components/schemas/ReportAnalyticsSections"
},
"includeAbstract": {
"type": "boolean"
},
"excludeFlaggedPostSummary": {
"type": "boolean"
},
"postTypesToAnalyze": {
"type": "array",
"items": {
"enum": [
"Post",
"Like",
"Reply",
"Repost"
],
"type": "string"
},
"description": "A list of post types that will be analyzed in the report. This list is exclusionary: if it is not empty,\r\nthen only the post types in this list will be analyzed. If the list is empty, all post types will be analyzed.",
"nullable": true
},
"showBehaviorIconsInReports": {
"type": "boolean",
"description": "Gets or sets a value indicating whether to show behavior icons on reports."
},
"redactNudeImagesInReports": {
"type": "boolean",
"description": "Gets or sets a value indicating whether to redact nude images in reports."
},
"group_posts_by": {
"type": "string",
"description": "String representation of Data.Models.Preferences.GeneralSettings.GroupPostsBy, because of\r\ninconsistency in the way enums are serialized in the API",
"nullable": true
},
"report_language_iso_code": {
"type": "string",
"description": "Gets or sets a value indicating report language ISO code",
"nullable": true
},
"includePostTagsInReports": {
"type": "boolean",
"description": "Boolean to indicate whether to include each post's Data.Models.Posts.Post.Tags in reports"
},
"hideSubjectProvidedPropertiesInReports": {
"type": "boolean",
"description": "Boolean to indicate whether to hide section with subject provided properties in reports."
},
"disableAutomaticAgenticSearch": {
"type": "boolean",
"description": "If true, prevents automatic agentic AI profile search from being initiated\r\nwhen a subject is assigned to an analyst or when a background check is initiated."
}
},
"additionalProperties": false
},
"GeoLocation": {
"type": "object",
"properties": {
"latitude": {
"type": "number",
"format": "double"
},
"longitude": {
"type": "number",
"format": "double"
}
},
"additionalProperties": false
},
"HandleSource": {
"enum": [
"Unknown",
"ManuallyAdded",
"ExternalApi",
"SubjectImport",
"DatabaseSearchResult",
"CandidateProfileResult",
"RelatedProfile",
"DocumentImport",
"AgenticSearch"
],
"type": "string"
},
"HandleStatus": {
"enum": [
"Valid",
"PrivateAccount",
"NoPublicPosts",
"Unverified"
],
"type": "string"
},
"IElasticSearchSettings": {
"type": "object",
"properties": {
"url": {
"type": "string",
"nullable": true
},
"indexName": {
"type": "string",
"nullable": true
},
"username": {
"type": "string",
"nullable": true
},
"password": {
"type": "string",
"nullable": true
},
"maxSearchResultChunkSize": {
"type": "integer",
"format": "int32"
},
"requestTimeoutInSeconds": {
"type": "integer",
"description": "The number of seconds to wait for a response from the Elasticsearch server. This is set\r\ninto a System.TimeSpan and used as the !:ConnectionSettings.RequestTimeout",
"format": "int32"
},
"certificateFingerprint": {
"type": "string",
"description": "The certificate fingerprint to use for SSL connections; found\r\nby examining the certificate in a browser after navigating to the\r\nData.Elasticsearch.IElasticSearchSettings.Url specified.",
"nullable": true
}
},
"additionalProperties": false
},
"ImageMatchType": {
"enum": [
0,
1
],
"type": "integer",
"format": "int32"
},
"ITableNames": {
"type": "object",
"properties": {
"subjects": {
"type": "string",
"nullable": true
},
"subjectSupplementaryDocumentsContainer": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false
},
"Keyword": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"include_in_search": {
"type": "boolean"
},
"keyword_type": {
"$ref": "#/components/schemas/KeywordType"
}
},
"additionalProperties": false
},
"KeyWords": {
"type": "object",
"properties": {
"is_active": {
"type": "boolean"
},
"key_words": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Keyword"
},
"nullable": true
}
},
"additionalProperties": false
},
"KeywordType": {
"enum": [
"Neutral",
"Positive",
"Negative",
"NotFlagged"
],
"type": "string"
},
"MediaItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Identifier for the media item",
"format": "uuid"
},
"type": {
"enum": [
"Image",
"VideoThumbnail",
"VideoFrame"
],
"type": "string",
"description": "The type of the media item"
},
"media": {
"type": "string",
"description": "URL representing the media item",
"nullable": true
},
"isVideo": {
"type": "boolean",
"description": "Boolean indicating whether the media is a video of some sort"
},
"videoLink": {
"type": "string",
"description": "Link to the video. The Data.Models.ExternalAPI.MediaItem.Media property sometimes represents a thumbnail image\r\nif the media item is a video.",
"nullable": true
},
"allFlags": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FlagInfo"
},
"description": "List of flag information",
"nullable": true
},
"friendlyFlagText": {
"type": "string",
"description": "Friendly text describing why the media item was flagged",
"nullable": true
},
"flagList": {
"type": "array",
"items": {
"type": "string"
},
"description": "Gets and sets a list of flags that are advertised in the UI (not all flags).",
"nullable": true
}
},
"additionalProperties": false
},
"NewSubject": {
"required": [
"subjectData"
],
"type": "object",
"properties": {
"subjectData": {
"$ref": "#/components/schemas/EditSubject"
},
"handles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ApiSubjectHandle"
},
"description": "Optional list of Data.Models.ExternalAPI.ApiSubjectHandle instances to add to the subject. Can be used instead of\r\nData.Models.ExternalAPI.EditSubject.FacebookUrl, Data.Models.ExternalAPI.EditSubject.InstagramUrl, or Data.Models.ExternalAPI.EditSubject.TwitterUrl (for example)\r\nto add handles to a subject.",
"nullable": true
},
"assignToFerretlyAnalyst": {
"type": "boolean",
"description": "Boolean indicating whether to assign the subject to a Ferretly analyst. The organization must have analyst assistance enabled.",
"example": true
},
"externalSystemId": {
"type": "string",
"description": "Optional but recommended identifier for the subject as it's known in the source system. This value will be included\r\nin webhook notifications and can be used in query methods such as !:SubjectsController.GetBackgroundCheckResultsByExternalId.",
"nullable": true,
"example": "ferretly_12345"
},
"ownerEmail": {
"type": "string",
"description": "Optional. If the subject should be assigned to a user other than the user associated with the API key,\r\nspecifies that user's email address. If the organization does not have a user with the specified\r\nemail address, then the new subject will be assigned to the user associated with the API key.",
"nullable": true,
"example": "john.smith@customer.com"
},
"document": {
"$ref": "#/components/schemas/UploadSubjectDocument"
},
"isDebug": {
"type": "boolean",
"description": "If true, the new subject will NOT BE ADDED to the database. This is useful for testing."
},
"organizationId": {
"type": "string",
"description": "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.",
"format": "uuid",
"nullable": true
},
"preferencesProfile": {
"type": "string",
"description": "(optional) The name or Guid id of the preference profile to use when creating the subject. If null or not specified,\r\nthe 'Default New Subject Profile' for the registered subscriber (usually the org admin) will be used.",
"nullable": true
},
"continuousScreening": {
"$ref": "#/components/schemas/NewSubjectContinuousScreening"
}
},
"additionalProperties": false,
"description": "Contains the data needed to create a new subject."
},
"NewSubjectContinuousScreening": {
"type": "object",
"properties": {
"isEnabled": {
"type": "boolean",
"description": "Whether continuous screening should be enabled for this subject.",
"example": true
},
"interval": {
"$ref": "#/components/schemas/ContinuousScreeningInterval"
},
"notificationEmail": {
"type": "string",
"description": "Optional email address to notify when a continuous screening background check completes.",
"format": "email",
"nullable": true,
"example": "alerts@customer.com"
}
},
"additionalProperties": false,
"description": "Continuous screening settings to apply when creating a new subject."
},
"OceanPersonalityTraits": {
"type": "object",
"properties": {
"openness": {
"type": "number",
"format": "double"
},
"conscientiousness": {
"type": "number",
"format": "double"
},
"extraversion": {
"type": "number",
"format": "double"
},
"agreeableness": {
"type": "number",
"format": "double"
},
"neuroticism": {
"type": "number",
"format": "double"
}
},
"additionalProperties": false,
"description": "Ocean5 (Big Five) personality traits model\r\nAll trait values are scaled from 0-100"
},
"Organization": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"nullable": true
},
"purchasedAnalystSupport": {
"type": "boolean",
"readOnly": true
},
"affiliate_guid": {
"type": "string",
"format": "uuid",
"nullable": true
},
"affiliate": {
"$ref": "#/components/schemas/AffiliateInfo"
},
"credits_available": {
"type": "integer",
"format": "int32"
},
"credits_used": {
"type": "integer",
"format": "int32"
},
"stripe_customerId": {
"type": "string",
"nullable": true
},
"socialMediaScraperYears": {
"type": "integer",
"format": "int32"
},
"planType": {
"$ref": "#/components/schemas/PlanType"
},
"paymentMethod": {
"$ref": "#/components/schemas/PaymentMethod"
},
"isSubscriptionActive": {
"type": "boolean"
},
"stripeSubscriptionId": {
"type": "string",
"nullable": true,
"deprecated": true
},
"stripePlanId": {
"type": "string",
"nullable": true,
"deprecated": true
},
"stripePricingId": {
"type": "string",
"nullable": true,
"deprecated": true
},
"numberOfContinuousScreeningSubjectsEnabled": {
"type": "integer",
"description": "The number of subjects for which continuous screening is enabled",
"format": "int64"
},
"piplCreditsAvailable": {
"type": "integer",
"format": "int32"
},
"piplCreditsUsed": {
"type": "integer",
"format": "int32"
},
"alternateDisclaimerText": {
"type": "string",
"description": "Text to use as an alternate disclaimer page",
"nullable": true
},
"data_retention_years": {
"type": "integer",
"description": "Number of years used for data retention",
"format": "int32"
},
"data_retention_period": {
"$ref": "#/components/schemas/DataRetentionPeriod"
},
"instructions": {
"type": "string",
"description": "Gets or sets the instructions for the organization",
"nullable": true
},
"pricingModel": {
"$ref": "#/components/schemas/PricingModel"
},
"isReseller": {
"type": "boolean",
"description": "Gets or sets whether the organization is a reseller.\r\nThis flag distinguishes resellers from standard organizations in the system."
},
"allowNegativeCredits": {
"type": "boolean",
"description": "When true, the organization is permitted to carry a negative credit balance.\r\nCharging flows will not reject requests when credits are at or below zero."
}
},
"additionalProperties": false,
"description": "Representation of an organization"
},
"OrganizationPreferencesProfile": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The unique identifier for this profile",
"format": "uuid"
},
"profile_name": {
"type": "string",
"nullable": true
},
"organizationId": {
"type": "string",
"description": "The organization to which this profile belongs",
"format": "uuid"
},
"organizationName": {
"type": "string",
"description": "The name of the organization",
"nullable": true
},
"isOrganizationDefaultProfile": {
"type": "boolean",
"description": "Whether or not this profile is the organization default",
"readOnly": true
},
"subscriberId": {
"type": "string",
"description": "If not null, this is a private profile",
"format": "uuid",
"nullable": true
},
"isPrivateProfile": {
"type": "boolean",
"readOnly": true
},
"isActive": {
"type": "boolean",
"description": "Support soft deletes of profiles"
},
"risk_categories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrganizationRiskCategory"
},
"nullable": true
},
"key_words": {
"$ref": "#/components/schemas/KeyWords"
},
"general_settings": {
"$ref": "#/components/schemas/GeneralSettings"
},
"disabledPlatforms": {
"type": "array",
"items": {
"enum": [
"Facebook",
"Instagram",
"Twitter",
"LinkedIn",
"TikTok",
"Reddit",
"Pinterest",
"YouTube"
],
"type": "string"
},
"description": "A list of social media platforms this profile has turned off. This list is exclusionary: if it is\r\nnot empty, then handles on those platforms are not scraped and profiles found there are not\r\nattached automatically. If the list is empty, every platform applies.",
"nullable": true
},
"lastEdited": {
"type": "string",
"format": "date-time"
},
"lastEditedBy": {
"type": "string",
"description": "The ID of the Data.Models.Subscriber who last edited this profile.\r\nNull when the profile was last edited via the external API.",
"format": "uuid",
"nullable": true
},
"lastEditedByName": {
"type": "string",
"description": "The display name of the person or system that last edited this profile.\r\nPopulated at write time. For human edits this is \"{FirstName} {LastName}\";\r\nfor external API edits this is the API client's Owner name.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Represents a preference profile applicable to an organization"
},
"OrganizationRiskCategory": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"format": "int32"
},
"name": {
"type": "string",
"nullable": true
},
"active": {
"type": "boolean"
},
"sort_order": {
"type": "integer",
"format": "int32"
},
"risk_type": {
"$ref": "#/components/schemas/RiskType"
}
},
"additionalProperties": false
},
"PaymentMethod": {
"enum": [
"InApp",
"Manual"
],
"type": "string"
},
"PlanType": {
"enum": [
"Free",
"Basic",
"Professional",
"Enterprise",
"SocialProfileSearch"
],
"type": "string",
"description": "Specifies the !:Organization.PlanType"
},
"Platform": {
"enum": [
"Development",
"Production",
"Staging"
],
"type": "string"
},
"PlatformSearchStatus": {
"type": "object",
"properties": {
"platform": {
"$ref": "#/components/schemas/SearchPlatform"
},
"status": {
"$ref": "#/components/schemas/SearchStatusEnum"
},
"startedOn": {
"type": "string",
"format": "date-time",
"nullable": true
},
"completedOn": {
"type": "string",
"format": "date-time",
"nullable": true
},
"statusMessage": {
"type": "string",
"nullable": true
},
"requestId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"timeoutMessageSequenceNumber": {
"type": "integer",
"description": "Sequence number of the scheduled Service Bus timeout message.\r\nSet by SearchProgressHandler when the search receives a slot (Started status).\r\nUsed by AgenticSearchCompletedHandler to cancel the timeout on completion.\r\nNull means no timeout has been scheduled yet (search is still queued).",
"format": "int64",
"nullable": true
}
},
"additionalProperties": false
},
"Post": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the post",
"format": "uuid"
},
"backgroundCheckId": {
"type": "string",
"description": "The background check which contains this post",
"format": "uuid"
},
"platform": {
"type": "string",
"description": "The name of the social media platform where this post was found",
"nullable": true
},
"postType": {
"$ref": "#/components/schemas/PostType"
},
"handle": {
"type": "string",
"description": "The \"handle\" (aka, username) of the person who authored the post",
"nullable": true
},
"nameOfPoster": {
"type": "string",
"description": "Friendly name of the person who authored the post",
"nullable": true
},
"profileImageUrl": {
"type": "string",
"description": "A URL to the profile picture of the person who authored the post",
"nullable": true
},
"postLink": {
"type": "string",
"description": "A URL to the original post",
"nullable": true
},
"content": {
"type": "string",
"description": "The post's content",
"nullable": true
},
"postDate": {
"type": "string",
"description": "The date/time of the post",
"format": "date-time"
},
"sentiment": {
"type": "number",
"description": "A measure of the post's \"sentiment\". Range from -1 (negative sentiment) to +1 (positive sentiment)",
"format": "double"
},
"sentimentFlag": {
"$ref": "#/components/schemas/SentimentFlag"
},
"flagList": {
"type": "array",
"items": {
"type": "string"
},
"description": "Gets and sets a list of flags that are advertised in the UI (not all flags). For keywords, may be set for posts that are not risks.",
"nullable": true
},
"allFlags": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FlagInfo"
},
"description": "Gets and sets the list of ALL flags found for this post (set on posts that are risks).",
"nullable": true
},
"friendlyFlagText": {
"type": "string",
"description": "The \"flag\" text displayed in the user interface.",
"nullable": true
},
"isVideo": {
"type": "boolean",
"description": "A boolean to indicate whether the primary media item is a video."
},
"videoLink": {
"type": "string",
"description": "A link to the video.",
"nullable": true
},
"mediaItems": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MediaItem"
},
"description": "A list of Data.Models.MediaItem if the post contains multiple.",
"nullable": true
},
"keywordFlagType": {
"$ref": "#/components/schemas/KeywordType"
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "A list of Tags that have been applied to the post.",
"nullable": true
}
},
"additionalProperties": false,
"description": "A social media, web/news, or custom URL item associated with the subject"
},
"PostDateFilter": {
"enum": [
"None",
"ThirtyDays",
"SincePrevious",
"Custom"
],
"type": "string"
},
"PostType": {
"enum": [
"Post",
"Reply",
"Like",
"Repost",
"MediaItemContent",
"WebSearch",
"CustomUrl"
],
"type": "string"
},
"PostTypeFilter": {
"enum": [
"All",
"NegativeSentiment",
"PositiveSentiment",
"Flagged",
"WebNews",
"Tagged",
"SavedSearch",
"SanctionsSearch"
],
"type": "string"
},
"PreferenceProfile": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the preferences profile",
"format": "uuid"
},
"profileName": {
"type": "string",
"description": "The name of the preferences profile",
"nullable": true,
"example": "Executive Screening"
},
"isOrganizationDefaultProfile": {
"type": "boolean",
"description": "A boolean indicating whether this profile is the organization's default profile",
"example": false
},
"subscriberId": {
"type": "string",
"description": "The ID of the user associated with a private preferences profile.",
"format": "uuid",
"nullable": true,
"example": null
},
"isPrivateProfile": {
"type": "boolean",
"description": "A boolean indicating whether this profile is private.",
"example": false
}
},
"additionalProperties": false,
"description": "High-level details about a preference profile associated with an\r\norganization."
},
"PreferenceProfileBehaviorCategory": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Gets or sets the identifier for the behavior category in the preference profile.\r\nThis property uniquely represents a behavior category within the context of the preference profile functionality.",
"format": "int32",
"example": 101
},
"name": {
"type": "string",
"description": "Gets or sets the name of the behavior category associated with the preference profile.\r\nThis property represents a descriptive label or title for the behavior category,\r\nenabling better context and readability in the preference profile configuration.",
"nullable": true,
"example": "Politics/Government"
},
"active": {
"type": "boolean",
"description": "Gets or sets a value indicating whether the behavior category is active.\r\nThis property determines if the behavior category is considered enabled\r\nwithin the context of the preference profile functionality."
},
"behaviorType": {
"$ref": "#/components/schemas/RiskType"
}
},
"additionalProperties": false,
"description": "A behavior category setting on a preference profile create or update request.\r\nOnly Data.Models.ExternalAPI.PreferenceProfileBehaviorCategory.Id, Data.Models.ExternalAPI.PreferenceProfileBehaviorCategory.Name, and Data.Models.ExternalAPI.PreferenceProfileBehaviorCategory.IsActive are settable\r\nthrough the External API."
},
"PreferenceProfileUpsert": {
"required": [
"profile_name"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"profile_name": {
"type": "string",
"description": "Gets or sets the name of the preference profile."
},
"behavior_categories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PreferenceProfileBehaviorCategory"
},
"description": "Gets or sets the list of behavior categories associated with a preference profile.",
"nullable": true
},
"key_words": {
"$ref": "#/components/schemas/KeyWords"
},
"general_settings": {
"$ref": "#/components/schemas/GeneralSettings"
},
"disabled_platforms": {
"type": "array",
"items": {
"enum": [
"Facebook",
"Instagram",
"Twitter",
"LinkedIn",
"TikTok",
"Reddit",
"Pinterest",
"YouTube"
],
"type": "string"
},
"description": "Gets or sets the social media platforms this profile turns off. Omit this field to leave the stored\r\nselection unchanged, send an empty list to turn every platform back on, or send a list of platforms\r\nto replace the selection.",
"nullable": true
}
},
"additionalProperties": false
},
"PricingModel": {
"enum": [
0,
1,
2
],
"type": "integer",
"description": "Represents the pricing model for a product",
"format": "int32"
},
"ProfileIdentifiers": {
"type": "object",
"properties": {
"isProvidedBySubject": {
"type": "boolean"
},
"isUniqueNameProvided": {
"type": "boolean"
},
"isNonUniqueNameProvided": {
"type": "boolean"
},
"isLocationProvided": {
"type": "boolean"
},
"isCompanyProvided": {
"type": "boolean"
},
"isCollegeProvided": {
"type": "boolean"
},
"isHighSchoolProvided": {
"type": "boolean"
},
"isThirdPartyDatabaseProvided": {
"type": "boolean"
},
"isUsernameProvided": {
"type": "boolean"
},
"isPhoneNumberProvided": {
"type": "boolean"
},
"isEmailProvided": {
"type": "boolean"
},
"isFaceMatchProvided": {
"type": "boolean"
},
"isAgeMatchProvided": {
"type": "boolean"
},
"otherNote": {
"type": "string",
"nullable": true
}
},
"additionalProperties": false,
"description": "A ProfileIdentifier represents the data that was provided in the profile"
},
"ReportAnalyticsSections": {
"type": "object",
"properties": {
"socialMediaScore": {
"type": "integer",
"format": "int32"
},
"riskMakeup": {
"type": "integer",
"format": "int32"
},
"socialProfileCounts": {
"type": "integer",
"format": "int32"
},
"wordCloud": {
"type": "integer",
"format": "int32"
},
"sentiment": {
"type": "integer",
"format": "int32"
},
"channelVolumes": {
"type": "integer",
"format": "int32"
},
"oceanPersonality": {
"type": "integer",
"format": "int32"
}
},
"additionalProperties": false,
"description": "Settings related to the Post Insights sections of the background report.\r\nThe value of the properties indicates their \"sort order\" on the page.\r\nIf a property's value is zero (see Data.Models.Preferences.ReportAnalyticsSections.SectionDisabled), then that section will not be visible in the report."
},
"RiskMakeup": {
"type": "object",
"properties": {
"riskName": {
"type": "string",
"description": "The name of the behavior",
"nullable": true,
"example": "Disparaging"
},
"count": {
"type": "integer",
"description": "Count of the number of posts flagged for this behavior",
"format": "int32",
"example": 5
}
},
"additionalProperties": false
},
"RiskType": {
"enum": [
"Post",
"Image",
"Keywords"
],
"type": "string"
},
"RunStatusEnum": {
"enum": [
"None",
"Started",
"Queued",
"ScrapingComplete",
"PostClassificationComplete",
"ImageClassificationComplete",
"ImageClassificationContinues",
"WebSearchComplete",
"RunCompleted",
"Error",
"ScraperFinished",
"SubjectHasNoPosts",
"BackgroundCheckTimedOut",
"ScreeningInProgress",
"PostsFetched",
"PostTranslationCheckStarted",
"PostTranslationCheckCompleted",
"PostTranslationStarted",
"PostTranslationComplete",
"ImageClassificationStarted",
"PostClassificationStarted",
"WebSearchStarted",
"ScoringPostsStarted",
"WebSearchIterationStarted",
"VideoProcessingStarted",
"VideoProcessingCompleted",
"VideoFramesExtractionPreparationStarted",
"VideoFramesExtractionPreparationCompleted",
"VideoFramesExtractionStarted",
"VideoFramesExtractionCompleted",
"FlaggedVideoFramesSavingStarted",
"FlaggedVideoFramesSavingCompleted"
],
"type": "string"
},
"SearchPlatform": {
"enum": [
1,
2,
3,
4,
5,
6,
7,
8,
9,
10
],
"type": "integer",
"description": "Enumeration of the various searchable platforms",
"format": "int32"
},
"SearchStatusEnum": {
"enum": [
0,
1,
2,
3,
4,
5
],
"type": "integer",
"format": "int32"
},
"SentimentFlag": {
"enum": [
"Neutral",
"Positive",
"Negative"
],
"type": "string"
},
"Subject": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"subscriberId": {
"type": "string",
"description": "The ID of the subscriber that added this subject or who currently \"owns\" it (see Data.Models.Subject.OwnerFirstName and Data.Models.Subject.OwnerLastName)",
"format": "uuid"
},
"ownerFirstName": {
"type": "string",
"description": "First name of the subscriber that added this subject or who currently \"owns\" it",
"nullable": true
},
"ownerLastName": {
"type": "string",
"description": "Last name of the subscriber that added this subject or who currently \"owns\" it",
"nullable": true
},
"ownerEmail": {
"type": "string",
"description": "Email of the subscriber that added this subject or who currently \"owns\" it",
"nullable": true
},
"ownerProfilePhotoUrl": {
"type": "string",
"description": "Profile photo url of the subscriber that added this subject or who currently \"owns\" it",
"nullable": true
},
"organizationId": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string",
"nullable": true
},
"nickname": {
"type": "string",
"description": "Another name/alias property for the subject",
"nullable": true
},
"handles": {
"type": "string",
"nullable": true
},
"handleList": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SubjectHandle"
},
"nullable": true
},
"mostRecentRunId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"dateAdded": {
"type": "string",
"format": "date-time",
"nullable": true
},
"subjectAddedAuditInfo": {
"$ref": "#/components/schemas/AuditInfo"
},
"profilePicUrl": {
"type": "string",
"nullable": true
},
"lastRunDate": {
"type": "string",
"description": "Represents the date/time that the most recent run completed",
"format": "date-time",
"nullable": true
},
"score": {
"type": "integer",
"format": "int32",
"nullable": true
},
"status": {
"$ref": "#/components/schemas/SubjectStatus"
},
"lastRunStatus": {
"$ref": "#/components/schemas/RunStatusEnum"
},
"lastRunStatusMessage": {
"type": "string",
"nullable": true
},
"lastRunFinishedScraping": {
"type": "string",
"format": "date-time",
"nullable": true
},
"currentRunStarted": {
"type": "string",
"format": "date-time",
"nullable": true
},
"currentBackgroundCheckStartedBy": {
"type": "string",
"nullable": true
},
"currentRunStatus": {
"$ref": "#/components/schemas/RunStatusEnum"
},
"currentRunId": {
"type": "string",
"format": "uuid",
"nullable": true
},
"backgroundReportFileName": {
"type": "string",
"description": "Gets and sets the name of a newly-generated\r\nbackground report file. Also sets Data.Models.Subject.IsBackgroundReportStale to false.",
"nullable": true
},
"isBackgroundReportStale": {
"type": "boolean",
"description": "A Boolean to indicate that there have been data\r\nchanges which cause the current background report\r\nfile to be outdated"
},
"address": {
"type": "string",
"nullable": true
},
"city": {
"type": "string",
"nullable": true
},
"state": {
"type": "string",
"nullable": true
},
"country": {
"type": "string",
"nullable": true
},
"coordinates": {
"$ref": "#/components/schemas/GeoLocation"
},
"email": {
"type": "string",
"nullable": true
},
"highSchool": {
"type": "string",
"nullable": true
},
"college": {
"type": "string",
"nullable": true
},
"company": {
"type": "string",
"nullable": true
},
"phoneNumber": {
"type": "string",
"nullable": true
},
"twitterUrl": {
"type": "string",
"nullable": true
},
"facebookUrl": {
"type": "string",
"nullable": true
},
"instagramUrl": {
"type": "string",
"nullable": true
},
"linkedInUrl": {
"type": "string",
"nullable": true
},
"tiktokUrl": {
"type": "string",
"nullable": true
},
"redditUrl": {
"type": "string",
"nullable": true
},
"pinterestUrl": {
"type": "string",
"nullable": true
},
"youtubeUrl": {
"type": "string",
"nullable": true
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"riskMakeups": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RiskMakeup"
},
"nullable": true
},
"channelVolumes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ChannelVolume"
},
"nullable": true
},
"isRedressed": {
"type": "boolean"
},
"lastMarkAsRedressedOn": {
"type": "string",
"format": "date-time",
"nullable": true
},
"lastMarkedAsRedressedBy": {
"type": "string",
"format": "uuid",
"nullable": true
},
"lastMarkedAsRedressedEmail": {
"type": "string",
"nullable": true
},
"lastMarkedAsRedressedName": {
"type": "string",
"nullable": true
},
"lastMarkedAsRedressedAuditInfo": {
"$ref": "#/components/schemas/AuditInfo"
},
"totalPosts": {
"type": "integer",
"description": "Note that this does not include Data.Models.Posts.PostType.WebSearch posts",
"format": "int32",
"readOnly": true
},
"flaggedPosts": {
"type": "integer",
"format": "int32"
},
"totalSentiment": {
"type": "number",
"format": "double"
},
"webSearchPosts": {
"type": "integer",
"format": "int32"
},
"sanctionsSearchPosts": {
"type": "integer",
"format": "int32"
},
"hasAvailablePosts": {
"type": "boolean",
"readOnly": true
},
"isBackgroundCheckInProgress": {
"type": "boolean",
"readOnly": true
},
"preferencesProfileID": {
"type": "string",
"description": "The ID of the Data.Models.Preferences.OrganizationPreferencesProfile used in background checks",
"format": "uuid",
"nullable": true
},
"isEnabledForContinuousScreening": {
"type": "boolean",
"description": "Boolean to indicate whether this subject is enabled for continuous screening"
},
"subscriberEnablingContinuousScreening": {
"type": "string",
"format": "uuid",
"nullable": true
},
"continuousScreeningPreferences": {
"$ref": "#/components/schemas/OrganizationPreferencesProfile"
},
"continuousScreeningInterval": {
"$ref": "#/components/schemas/ContinuousScreeningInterval"
},
"continuousScreeningHourBucket": {
"type": "integer",
"description": "Round-robin hour-of-day bucket (0-23) this subject's Daily-interval continuous\r\nscreening run is assigned to. Only set when Data.Models.Subject.ContinuousScreeningInterval\r\nis Ferretly.Common.Subjects.ContinuousScreeningInterval.Daily; null for Monthly+ subjects and\r\nwhen continuous screening is disabled.",
"format": "int32",
"nullable": true
},
"continuousScreeningNotificationEmail": {
"type": "string",
"nullable": true
},
"continuousScreeningLastCreditChargedAt": {
"type": "string",
"description": "The date/time when a credit was last charged for a continuous screening background check for this subject.\r\nUsed to determine whether a credit should be charged when a new continuous screening check is initiated\r\n(a charge is made if this is null or more than 12 months ago).",
"format": "date-time",
"nullable": true
},
"supplementaryDocumentBlobName": {
"type": "string",
"nullable": true
},
"supplementaryDocumentFilename": {
"type": "string",
"nullable": true
},
"supplementaryDocumentContentType": {
"type": "string",
"nullable": true
},
"previousRunDate": {
"type": "string",
"format": "date-time",
"nullable": true
},
"nextScreeningDate": {
"type": "string",
"format": "date-time",
"nullable": true
},
"originalScreeningDate": {
"type": "string",
"format": "date-time",
"nullable": true
},
"isAssignedToFerretlyAnalyst": {
"type": "boolean"
},
"dateAssignedToAnalyst": {
"type": "string",
"format": "date-time",
"nullable": true
},
"assignedToAnalystAuditInfo": {
"$ref": "#/components/schemas/AuditInfo"
},
"assignedAnalystId": {
"type": "string",
"description": "Gets and sets the ID of the analyst assigned to this subject",
"format": "uuid",
"nullable": true
},
"slaTimeInHours": {
"type": "integer",
"description": "Gets or sets the number of hours that was used for calculating SLA expiration time.",
"format": "int32",
"nullable": true
},
"slaExpirationTime": {
"type": "string",
"description": "Gets and sets the date/time when the SLA expires.",
"format": "date-time",
"nullable": true
},
"turnAroundTimeInHours": {
"type": "number",
"description": "Gets and sets the turn-around, in hours, for this subject. The calculation is performed\r\ndifferently for subjects assigned to an analyst than otherwise.",
"format": "double",
"nullable": true
},
"ageOrDateOfBirth": {
"type": "string",
"nullable": true
},
"isExternalApiSubject": {
"type": "boolean",
"description": "Indicates whether the subject was created via the external API"
},
"externalSystemId": {
"type": "string",
"description": "An identifier for the subject as it's known to the external system",
"nullable": true
},
"isPostMigrationScheduled": {
"type": "boolean"
},
"areSubjectProfilesReviewed": {
"type": "boolean",
"description": "Indicates whether the subject’s profiles have been reviewed by Analyst after search"
},
"runBGCheckAfterSearchIsFinished": {
"type": "boolean",
"description": "If true, a background check will be automatically triggered after agentic search\r\ncompletes profile validation, provided the organization has no Analyst Assistance."
},
"notes": {
"type": "string",
"description": "Notes about this subject. Free-form text.",
"nullable": true
},
"lastUpdated": {
"type": "string",
"description": "Date/time of the last update to this subject",
"format": "date-time",
"nullable": true,
"readOnly": true
},
"lastUpdatedBy": {
"type": "string",
"description": "The name of the person who last updated this subject",
"nullable": true,
"readOnly": true
},
"lastUpdatedByEmail": {
"type": "string",
"description": "The email address of the person who last updated this subject",
"nullable": true,
"readOnly": true
},
"lastUpdatedBySubscriberId": {
"type": "string",
"description": "The ID of the subscriber who last updated this subject",
"format": "uuid",
"nullable": true,
"readOnly": true
},
"lastUpdatedAuditInfo": {
"$ref": "#/components/schemas/AuditInfo"
},
"platformSearchStatuses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PlatformSearchStatus"
},
"nullable": true
},
"hasAgenticProfileSearch": {
"type": "boolean",
"description": "True if an Agentic Profile Search has been initiated for this subject at least once.\r\nA credit is charged on first initiation, so this indicates that credit has been paid\r\nand the first background check can be run without an additional charge.",
"readOnly": true
},
"postSummaryText": {
"type": "string",
"description": "A string that represents AI-generated text that summarizes the subject's most-recent flagged posts",
"nullable": true
},
"oceanPersonalityTraits": {
"$ref": "#/components/schemas/OceanPersonalityTraits"
},
"partitionKey": {
"type": "string",
"nullable": true
},
"rowKey": {
"type": "string",
"nullable": true
},
"timestamp": {
"type": "string",
"format": "date-time",
"nullable": true
},
"eTag": {
"$ref": "#/components/schemas/ETag"
}
},
"additionalProperties": false
},
"SubjectHandle": {
"type": "object",
"properties": {
"platform": {
"type": "string",
"description": "Override the platform JSON output so that we get the correct casing. A value naming no known\r\nplatform falls through as stored instead of becoming null, so it stays visible in an API response,\r\nand the setter writes the stored one, so this carries the inbound bind as well as the outbound.",
"nullable": true
},
"isSubjectProvided": {
"type": "boolean"
},
"verified": {
"type": "boolean"
},
"profileUrl": {
"type": "string",
"nullable": true
},
"profilePicUrl": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"location": {
"type": "string",
"nullable": true
},
"workplace": {
"type": "string",
"nullable": true
},
"school": {
"type": "string",
"nullable": true
},
"livesIn": {
"type": "string",
"nullable": true
},
"from": {
"type": "string",
"nullable": true
},
"livesInCoordinates": {
"$ref": "#/components/schemas/GeoLocation"
},
"fromCoordinates": {
"$ref": "#/components/schemas/GeoLocation"
},
"facebookStatus": {
"type": "string",
"nullable": true
},
"socialMediaLinkedAccount": {
"type": "string",
"nullable": true
},
"joined": {
"type": "string",
"format": "date-time"
},
"postCount": {
"type": "integer",
"format": "int32"
},
"followers": {
"type": "integer",
"format": "int32"
},
"following": {
"type": "integer",
"format": "int32"
},
"bio": {
"type": "string",
"nullable": true
},
"status": {
"$ref": "#/components/schemas/HandleStatus"
},
"socialMediaProfileId": {
"type": "string",
"nullable": true
},
"candidateProfileId": {
"type": "string",
"description": "The ID of the CandidateProfile that this handle is associated with.",
"format": "uuid",
"nullable": true
},
"handleCreated": {
"type": "string",
"format": "date-time",
"nullable": true
},
"validationStarted": {
"type": "string",
"format": "date-time",
"nullable": true
},
"validationCompleted": {
"type": "string",
"format": "date-time",
"nullable": true
},
"candidateProfile": {
"$ref": "#/components/schemas/CandidateProfileModel"
},
"handleSource": {
"$ref": "#/components/schemas/HandleSource"
},
"pronouns": {
"type": "string",
"description": "Gets and sets any pronouns that are associated with this handle.",
"nullable": true
},
"handle": {
"type": "string",
"nullable": true
},
"isPersonalProfile": {
"type": "boolean",
"description": "Indicates whether this handle represents a personal profile, as opposed to a business or organization page.",
"example": true
}
},
"additionalProperties": false
},
"SubjectStatus": {
"enum": [
"Demo",
"Active",
"Archived"
],
"type": "string"
},
"UploadSubjectDocument": {
"type": "object",
"properties": {
"filename": {
"type": "string",
"description": "Required name for the document to be uploaded",
"nullable": true
},
"contentType": {
"type": "string",
"description": "Required content type for the document to be uploaded",
"nullable": true
},
"imageData": {
"type": "string",
"description": "Required base64-encoded content for the document to be uploaded",
"format": "byte",
"nullable": true
}
},
"additionalProperties": false,
"description": "Represents a document which will be associated with the newly-created subject"
}
},
"securitySchemes": {
"ApiKey": {
"type": "apiKey",
"description": "API key authentication. Pass your API key in the X-Api-Key request header.",
"name": "X-Api-Key",
"in": "header"
}
},
"callbacks": {
"FerretlyStatusChange": {
"{$request.body}": {
"get": {
"summary": "Screening status notification",
"description": "Ferretly appends URL-encoded subjectId, status, and externalSystemId query parameters and performs an HTTP GET. There is no JSON event body, Authorization header or cryptographic signature. Process the delivered status idempotently. For Analyst Assistance, handle Redressed and Complete without duplicating completion work.",
"security": [],
"parameters": [
{
"name": "subjectId",
"in": "query",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
},
"description": "Ferretly subject identifier."
},
{
"name": "status",
"in": "query",
"required": true,
"schema": {
"$ref": "#/components/schemas/BackgroundCheckStatus"
},
"description": "Screening status; Redressed can also be sent when an analyst marks the subject as reviewed."
},
{
"name": "externalSystemId",
"in": "query",
"required": true,
"allowEmptyValue": true,
"schema": {
"type": "string"
},
"description": "External identifier from subject creation, or an empty string if none was supplied."
}
],
"responses": {
"2XX": {
"description": "Acknowledge receipt. Schedule any result retrieval or processing independently."
}
},
"x-implementation-source": "Ferretly release implementation reviewed 2026-10-14",
"x-delivery-guidance": "Retry behavior can change without notice and may vary by organization. Do not assume exactly-once delivery, a fixed retry schedule or strict ordering."
}
}
}
}
},
"security": [
{
"ApiKey": []
}
],
"tags": [
{
"name": "ApiClient",
"description": "Endpoints for discovering information about and managing Data.Models.ExternalAPI.ApiClient instances."
},
{
"name": "PreferenceProfiles",
"description": "The PreferenceProfilesController provides endpoints to manage the\r\norganization-wide preference profiles related to an authenticated client."
},
{
"name": "Subjects",
"description": "Endpoints for creating, discovering, and managing Ferretly subject records associated with an API client"
}
],
"x-documentation-status": "live-contract-snapshot",
"x-documentation-source": {
"url": "https://api.ferretly.com/swagger/v1/swagger.json",
"checkedDate": "2026-10-19",
"sha256": "0adc71a23fe32a82ea9fb7aefa91966f8b7fda2fe673fd9f38eb4f2e921d0ef1"
},
"x-documentation-extensions": {
"callbacks": {
"origin": "Ferretly release-source review",
"checkedDate": "2026-10-19"
},
"subjectCreationNotes": {
"repository": "craigeddy/ferretly-backend",
"branch": "BlackFoot",
"commit": "ab9d7f2a53fd00f5ddd524ce8738df043c00285c",
"path": "DataAPI/Models/Models/ExternalAPI/EditSubject.cs",
"status": "Source-backed; absent from the live Swagger request schema. Deployed write support not tested."
},
"healthAuthentication": {
"origin": "HealthController and unauthenticated HTTP 200",
"checkedDate": "2026-10-19"
}
}
}