Best practices

Keep credentials on your server

Send the private key through X-Api-Key. Use GET /api/ApiClient to verify access and inspect configuration. Keep keys out of browser bundles, URLs, client logs, and support messages.

Coordinate rotation; do not assume the old key stops working immediately. See Authentication.

Follow your organization’s workflow

Confirm whether Analyst Assistance is enabled for your organization. Use the Analyst Assistance guide when it is, or the workflow without Analyst Assistance otherwise. This service configuration is agreed with Ferretly, not independently selected by the API developer.

For Analyst Assistance, do not call initiateBackgroundCheck. Ferretly analysts manage the workflow; use review-completion callbacks before retrieving results.

See Screening model.

Use debug mode carefully

isDebug: true skips saving the subject. Other actions can still occur: analyst assignment can enqueue work, validation can call other services, and daily continuous screening can allocate a scheduling bucket.

Keep assignToFerretlyAnalyst: false and omit continuous screening for request-shape checks. Ferretly does not provide a separate integration test environment; requests use your organization’s data. A debug response’s ID does not identify a saved subject, so subsequent lookups return an error. Arrange real analyst-assisted test work with your Ferretly contact.

Reconcile before retrying writes

Store the returned subject ID and your unique external ID. After an uncertain create response, look up and reconcile the subject before retrying. External IDs do not prevent duplicate creation.

Some documented GET operations change state, including API-key rotation. Follow the action-specific guidance and do not let HTTP-method assumptions trigger unsafe automatic retries.

Use callbacks as notifications

Accept GET callbacks, acknowledge promptly, and process the delivered status idempotently. Retrieve results after completion rather than rechecking the status for every notification. The sender does not add a signature, event ID or run ID.

See Webhook setup for query parameters, receiver verification options and delivery guidance.

Plan for API limits

• Subject listings are size-limited and do not support pagination.
• Filtered posts expose typeFilter and dateFilter, not arbitrary platform or date-range query parameters.
• Preference-profile write models differ from read models.
• Confirm request volumes and callback configuration with Ferretly Integrations before a high-volume rollout.

Use only the parameters listed for each endpoint. Reconcile uncertain writes before retrying; do not rely on an idempotency header to prevent duplicates.

Keep results and reports separate

Results are aggregated JSON; posts use separate endpoints; reports are binary downloads. Report regeneration can temporarily prevent download. Do not start another screening solely because a report is not yet available.

For help, follow the support guide and provide a redacted diagnostic summary.