Identity and IDs

Keep both identifiers

Identifier	Supplied by	Usage
Subject ID	Ferretly	The id returned by create; UUID paths using subjectId
External system ID	Your integration	externalSystemId on create; lookup paths using externalId; callback query parameter externalSystemId

Store both after a successful create. Use opaque, stable identifiers instead of embedding sensitive identity data in external IDs.

Lookup routes

GET /api/Subjects/{subjectId}
GET /api/Subjects/getByExternalId/{externalId}
GET /api/Subjects/{subjectId}/screeningstatus
GET /api/Subjects/{externalId}/screeningStatusByExternalId
GET /api/Subjects/{subjectId}/backgroundCheckResults
GET /api/Subjects/getByExternalId/{externalId}/backgroundCheckResults
GET /api/Subjects/{subjectId}/filteredPosts
GET /api/Subjects/{externalId}/filteredPostsByExternalId

URL-encode external identifiers when inserting them into a route.

Duplicate external IDs

External-ID lookup is scoped to your organization and requires an exact match. If multiple subjects share an external ID, the endpoint returns the first match; the order is not guaranteed.

Keep external IDs unique for each person within your integration. If duplicates exist, use the Ferretly subject ID. The create operation does not advertise an idempotency key or a uniqueness guarantee for externalSystemId.

Reconcile an uncertain create

A network timeout does not prove that subject creation failed. Look up the expected external ID and reconcile the returned record before attempting another create. If the identifier is ambiguous, resolve it rather than assuming the first result is the record you intended.

Do not use a debug response ID to start a real screening; debug mode does not insert that subject.