Synchronous and Asynchronous Endpoints
Write endpoints fall into two categories. The HTTP success status code tells you which is which.
Synchronous (200 OK / 201 Created)
The response body contains the final state of the resource. No follow-up calls are required.
| Endpoint family | Success status | Returns |
|---|---|---|
All read endpoints (GET ...) |
200 |
Resource (or paginated list) |
POST /v1/programs, POST /v1/programs/{uuid}/entities, POST /v1/programs/{uuid}/monitors, POST /v1/entities/{uuid}/notes |
201 |
Created resource |
PATCH / DELETE on any resource |
200 |
Updated or soft-deleted resource |
POST /v1/entities/{uuid}/archive, POST /v1/entities/{uuid}/unarchive |
200 |
Updated entity |
POST /v1/entities/{uuid}/id-checks, POST /v1/adhoc-id-checks |
200 |
Completed ID check (full payload, including the final outcome) |
Identity verification checks are run synchronously against the upstream provider before the response is returned - the outcome (pass/fail) is final by the time you get the response. The one exception is an ID check completed through an IDPass verification, which reports pending until the person finishes (see IDPass); otherwise there is no pending state to poll for ID checks.
Asynchronous (202 Accepted)
The response confirms that the work has been queued. The actual screening runs in the background and you must poll the corresponding show endpoint until status (or, for monitor runs, process_status) reaches a terminal value.
| Launch endpoint | Poll | Terminal values |
|---|---|---|
POST /v1/entities/{uuid}/checks |
GET /v1/checks/{uuid} |
status is complete or failed |
POST /v1/adhoc-checks |
GET /v1/adhoc-checks/{uuid} |
status is complete or failed |
POST /v1/monitors/{uuid}/run |
GET /v1/monitors/{uuid} |
process_status is null (idle again), failed or paused |
The launch response carries the new resource's uuid (and on checks, a detail_url you can use directly). A reasonable polling cadence is every 2-5 seconds for the first 30 seconds, backing off to every 15-30 seconds for longer-running operations. Most screening checks complete within a few seconds; a monitor run across thousands of entities can take several minutes.
Idempotency interacts with polling
When you retry an async launch endpoint with the same Idempotency-Key, the replayed 202 response carries the same uuid as the original call (and an additional Idempotent-Replay: true response header). The background work was already queued by the original call - keep polling the original uuid rather than launching a new one. See Idempotency for the full contract.