Skip to content
Datasource Background Check Partner API

Changelog

Changes to the partner API, newest first. Changes are additive; a breaking change gets 90 days' notice here and by email.

2026-11-14

  • Fixed (docs): the OpenAPI stage enum now lists applicant_ready, which checks have reported since 2026-10-27. The duplicate_check example in the error catalog now shows the current check shape (id is a chk_... string), and the guide says that a webhook retry resends the identical body (same eventId and timestamp). No API behaviour changed.
  • New: sandbox keys are self-serve. Sign up at https://join.cbgc.io/sandbox/, confirm your email, and get a pk_test_ key and webhook secret (shown once). Production keys still come from Datasource once your sandbox integration works.

2026-10-27

  • New: check.expiring webhook, 30 days and again 7 days before a CLEAR or REVIEW check's expirationDate.
  • New: POST /clients/{clientRef}/checks/{checkRef}/remind re-sends the applicant's invitation (at most hourly, while the check is awaiting_applicant). New errors check_not_awaiting_applicant and reminder_too_soon.
  • New: reportUrl on CLEAR and REVIEW checks (the report in the church's portal; needs the church's sign-in) and charges (US dollars) on finished checks, on the check and in check.updated.
  • New: an invitation that expires before the applicant finishes closes the check as ERROR with errorCode invitation_expired.
  • New: GET /settings/webhook-deliveries, the last 30 days of webhook delivery attempts and how your endpoint answered.
  • New: errorCode and errorMessage on ERROR checks and in their check.updated: why the check failed and what to fix (for example missing_job_location). Null for every other status.
  • Changed: completedAt (and so expirationDate) is the screening provider's own completion time when it gives one, not the time we learned of it.
  • New: GET and PUT /clients/{clientRef}/settings with checkValidityYears (1 to 5, or null): how long that church's CLEAR and REVIEW checks stay valid. It overrides your account's default (checkValidityYears in PUT /settings), which still applies to churches without their own.
  • New: checkValidityYears in PUT /settings (1 to 5, default 2): how long a CLEAR or REVIEW check stays valid. expirationDate is now completedAt plus that many years, and is set only on CLEAR and REVIEW. Before, an open check could carry the expiry of the applicant's invitation link as its expirationDate; it no longer does.
  • New: stage applicant_ready. The applicant finished the form, but the order is held for the church to review and release in its Datasource portal (usually a possible duplicate or a jurisdiction question). Show it to the church's staff as needing action, with the client's portalUrl. Once released, the stage becomes in_progress. The status stays CREATED.
  • Fixed: a forceReorder for an applicant whose check is still open, or with a different externalIdentifier, is now a new check with its own id. Before, it replaced the open check (its externalIdentifier changed and its order was no longer tracked). Ordering again with the same externalIdentifier still reuses that check, and now clears its old completedAt and expirationDate.
  • New: stage in_progress is now reported. A CREATED check moves from awaiting_applicant to in_progress when the applicant finishes the form, and you get check.updated. The status stays CREATED.
  • Changed: check.updated is sent only when a check's status or stage changes, not on every update from the screening provider.
  • New: optional applicantPhone on orders (phone per batch applicant): the applicant's mobile number. When sent, the invitation is also texted to it; the email is still sent.

2026-10-21

Breaking, made before go-live (no partner is live yet):

  • Changed: clients are identified by clientId (cl_ followed by 24 characters), which replaces clientGuid in every response and webhook (check.updated, batch.completed, client.connected, client.migrated) and in GET /connect/sessions/{sessionId}. {clientRef} accepts clientId or your externalClientId.
  • Changed: a check's id is a string (chk_ followed by 24 characters) set when the check is ordered. orderId is removed from checks and check.updated; the replay-webhook response has id instead of orderId. The check path segment is {checkRef}: the check's id or your externalIdentifier.
  • Changed: a completed check is CLEAR when the screening provider reports that no search found records, and REVIEW (flagged) otherwise. Before, every completed check was REVIEW. A provider status of "pending review" is now CREATED (in progress), not REVIEW.
  • New: optional jobLocation and stateOfEmployment on orders and batches (and per batch applicant): where the applicant will work, as the church gives it. Some levels require both; we pass them on unchanged and never fill them in.
  • Removed: GET /clients/{clientRef}/packages and ordering by packageCode. Order by level (GET /products).
  • Changed: a cursor from before this change is 400 invalid_cursor; start the listing again without one.
  • Changed: a contact phone number must be a 10-digit US or Canadian number (any format, e.g. 801-555-1234); anything else is 400 validation_failed instead of 502.

2026-10-17

  • New: eventId on every webhook (the same on every retry of one event). Use it to drop repeated deliveries.
  • New: status on client.connected (always Active).
  • Changed: an externalIdentifier is unique across all your clients. Ordering with one that belongs to another client's check is 409 external_identifier_in_use (an invalid item in a batch); before, it re-used that check.
  • Changed: a check left PENDING by a lost submission answer now resolves on its own within about an hour (its real status, or ERROR if it never reached the screening provider), with check.updated.
  • Changed: a completed result is CLEAR only when the screening provider says it is clear; otherwise REVIEW.
  • Changed: 502 upstream_unavailable on ordering when the church's account couldn't be prepared: nothing was created, and a retry is safe.
  • Changed: invalid_cursor is now the code for a bad cursor (it was validation_failed).
  • New: problem responses written by the framework carry a code too: invalid_json, not_found, method_not_allowed, payload_too_large, unsupported_media_type, internal_error, request_failed.
  • POST /clients no longer returns temporaryPassword: like the connect page, the primary contact gets their sign-in by email from Datasource. The response has welcomeEmailSent instead, and primaryUsername may be a derived name when the email is already a login.
  • Connect page: the church's primary contact gets a sign-in email from Datasource with a temporary password. Submitting the page twice is safe. Invoice billing takes the billing setup copied from your account.
  • Docs: the guide is reorganized into 16 chapters with field tables, limits, status transitions, a reconciliation recipe and a test plan; the reference has enums, formats, limits and examples for every type; /llms-full.txt includes every operation's parameters and full JSON examples.

2026-10-16

  • Errors now carry a stable code and a type URI that points at /docs/errors.md.
  • Hosted documentation: /docs/guide.md, /docs/errors.md, /docs/changelog.md, /llms.txt, /llms-full.txt.
  • New: externalClientId on clients; {clientRef} accepts it in every client route; GET /clients?externalClientId=.
  • New: product levels (GET /products, GET /clients/{clientRef}/products) and level on orders.
  • New: orderedBy on orders (recorded as an order note only).
  • New: POST /clients/{clientRef}/checks/batch and GET /batches/{batchId}.
  • New: stage on checks and check.updated; QUEUED status; portalUrl on clients.
  • New webhook events: batch.completed, client.connected, client.migrated, ping. Ignore events you don't know.
  • New: partner settings (/settings): register your webhook and return URLs, rotate the webhook secret, send a test ping.
  • New: the hosted connect page (POST /connect/sessions, GET /connect/sessions/{sessionId}).
  • New: POST /clients/{clientRef}/checks/lookup (latest check per email, by index; emails are never returned) and PATCH /clients/{clientRef}/checks/{orderId} (set your own externalIdentifier once), for linking a migrated church's history to your people.