Subjects

A subject represents the person whose information is being screened. Creating a subject and completing the screening workflow are separate steps. Follow the path configured for your organization: with Analyst Assistance or without Analyst Assistance.

Subject data model

Model	Purpose
NewSubject	Creation wrapper, including subjectData, assignment and your external ID
EditSubject	Identity details and named profile URL fields inside subjectData
ApiSubjectHandle	Explicit known-profile input in handles
NewSubjectContinuousScreening	Optional recurring-screening configuration
Subject	Created or retrieved subject, including its id, handleList and notes

Include subjectData.name in every create request. Retain the returned id and your externalSystemId. The create request uses handles; the response uses handleList.

Identity details and ownership

Supply the identity information you have, such as location, email, employer and school. Use the exact field names in EditSubject.

ownerEmail is optional. If omitted, the subject belongs to the API-key user. A requested owner must belong to the organization; an unrecognized email falls back to the API-key user.

assignToFerretlyAnalyst should reflect the workflow agreed with Ferretly for your organization. It is not a way to enable an Analyst Assistance service the organization does not have.

Supply known social profiles

Use facebookUrl, instagramUrl, twitterUrl, linkedInUrl, tiktokUrl, redditUrl, pinterestUrl and youtubeUrl inside subjectData for named profile URLs. Use handles for explicit profile entries, including additional profiles on a platform.

You can combine the two forms. If you supply the same profile more than once, the API ignores the duplicate. The permitted number of handles per platform is configured by Ferretly; exceeding it returns HTTP 400 Bad Request. Contact Ferretly Integrations to confirm your organization’s limit.

The following example checks the request shape without saving a subject. Its identities and URLs are illustrative.

{
  "subjectData": {
    "name": "Example Candidate",
    "linkedInUrl": "https://www.linkedin.com/in/your-candidate"
  },
  "handles": [
    {
      "platform": "Twitter",
      "handle": "your_candidate",
      "profileUrl": "https://x.com/your_candidate"
    }
  ],
  "externalSystemId": "candidate-001",
  "assignToFerretlyAnalyst": false,
  "isDebug": true
}

Debug responses are not saved subjects

Ferretly does not provide a separate integration test environment; requests use your organization’s data. With isDebug: true, no subject is saved. Fetching that response’s ID later returns an error. Keep analyst assignment disabled when checking request shape; see the debug quickstart.

Read the create response

A successful POST /api/Subjects returns HTTP 200 with a Subject. Store its identifiers. Returned handles can initially show verified: false or Unverified; this does not mean the subject was not created. Handle validation is separate from the create response.

Response	Meaning / next action
200	Subject returned; debug responses are constructed without saving
400	Invalid creation input, exceeded per-platform handle limit, or Analyst Assistance requested for an organization without that service; read the returned error
401	Missing or invalid API credentials; correct authentication before retrying
403	A permission or feature gate prevents the request; confirm access with Ferretly
5xx or an uncertain network response	Reconcile whether the subject was created before retrying

The create-subject reference lists the responses advertised by the current contract. Authentication and service-level errors can also occur; see Errors and status codes. External IDs support lookup but do not prevent duplicate creation.

Using the Subject Object’s Notes Field

The optional notes field stores free-form context about the subject, such as information for a reviewing analyst. Get-subject responses return it as notes, a nullable string. The updated creation model accepts it as subjectData.notes.

If creation-side Notes is not yet listed in your deployment’s Swagger request schema, confirm deployed support with Integrations before relying on it. See the create-subject reference and get-subject reference.

Status and schema conventions

BackgroundCheckStatus describes workflow progress and review; RunStatusEnum describes detailed processing in results. Neither is the subject’s own status.

Use exact JSON property names and respect nullable and read-only annotations. The OpenAPI specification contains the full machine-readable schema set; preference-profile and post models are documented in their own guides.