Glossary

Use this glossary alongside the screening model and API reference.

Accounts and access

Term	Meaning
API client / ExternalClient	The configuration associated with an integration’s API key. It identifies the client organization and includes settings such as the status callback URL. The API returns an ApiClient model.
Organization	The Ferretly account containing your users, subjects, screening preferences, and entitlements. API access is scoped to the organization associated with your key.
Subscriber / owner	A Ferretly user associated with a subject. ownerEmail can request a different owner within your organization; an unknown email falls back to the user associated with the API key.
API key / APIKey	The private credential sent in the X-Api-Key request header. See Authentication.
Analyst assistance	An organization entitlement under which Ferretly analysts resolve identity, manage the screening workflow and review findings. See the analyst workflow.

Subjects and identifiers

Term	Meaning
Subject	The person whose online information is being screened. Creating a subject and completing a screening are separate steps.
Subject ID / SubjectId	The Ferretly-generated UUID returned as the subject’s id. Use it for routes containing subjectId.
External system ID / ExternalSystemId	Your identifier, supplied as externalSystemId during creation. Routes containing externalId look up this value; callbacks call it externalSystemId. It is not a duplicate-prevention or idempotency key. See Identity and IDs.
Handle	A social profile associated with a subject. Creation accepts profile URL fields or a handles array. Returned subjects expose handleList, including validation status.
AssignToFerretlyAnalyst	The assignToFerretlyAnalyst create option. Set it to true for an agreed analyst-assisted workflow; the organization must have analyst support enabled.
Preference profile	A named set of screening settings, behavior categories, keywords, and platform preferences. Creation accepts an existing profile’s name or UUID in preferencesProfile.

Screening and results

Term	Meaning
Background check / screening run	A processing run for a subject. A subject can have more than one run over time. Status, results, posts, and report operations have different purposes.
Screening status	The processing or review state returned by a status endpoint. This differs from the subject’s own status (Demo, Active, or Archived). See Status meanings.
Redressing	Analyst review remains outstanding after processing. Wait for Complete before treating the analyst workflow as finished.
Redressed	An additional callback event indicating that the subject was marked as reviewed; handle it alongside Complete without duplicating completion work.
Results	Aggregate findings from the most recent completed screening, retrieved through a results endpoint when available.
Post	A social media item, web/news result, or custom URL associated with the subject. Inspect postType to distinguish original content, replies, likes, and reposts.
Media item	An image, video thumbnail, or video frame attached to a post. Each media item can contain its own analysis flags.
Flag	An analysis result associated with a post or media item. Display labels, detailed flags, keyword matches, and sentiment serve different purposes. See Posts and media.
Report	The downloadable background report. A completed screening can still have a temporarily unavailable or regenerating report. See Results and reports.
Webhook / status callback	An HTTP GET request from Ferretly to your callback URL carrying subjectId, status, and externalSystemId as query parameters. See Webhooks.
Continuous screening	Recurring screening configured for an eligible subject and organization. See Continuous screening.

JSON property names are case-sensitive. Use the exact spellings shown in each request and response schema. Most models use camelCase; preference-profile models also contain snake_case fields.