Prembly
GuidesAPI Reference
Background ChecksRequestsStart a background check POST
POST
/api/v1/api/bgc/requests/candidates/{reference}/start-check/

Sends a candidate's submitted details to the verification provider and begins the checks.

Only valid while the request is submitted — that is, after the candidate has completed their form. Calling it in any other state returns 409 with the current status, so use that status rather than retrying.

Progress is reported back through the status webhook; this call returns once the work has been accepted, not once it is finished.

Authorization

ApiKeyAuth
X-API-Key<token>

In: header

Path Parameters

reference*string

Candidate request reference, returned as reference when the request was created.

Formatuuid

Response Body

application/json

curl -X POST "https://example.com/api/v1/api/bgc/requests/candidates/497f6eca-6276-4993-bfeb-53cbbbba6f08/start-check/"
{  "data": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "candidate_name": "string",    "candidate_email": "user@example.com",    "status": "pending",    "response_submitted": true,    "organisation": "string",    "package": "string",    "created_by": "string",    "reference": "2ddb20b8-e0e3-45ae-a638-42610b990a6a",    "verification_id": "string",    "service_type": "string",    "payment_reference": "string",    "payment_gateway": "string",    "payment_status": "string",    "additional_fields": null,    "candidate_submitted_data": null,    "notification_preferences": null,    "editing_history": null,    "current_editing_fields": "string",    "cancellation_reason": "string",    "cancelled_at": "2019-08-24T14:15:22Z",    "is_active": true,    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  },  "status": true,  "message": "Request successful.",  "errors": {},  "meta": {    "timestamp": "2019-08-24T14:15:22Z",    "version": "v1",    "request_id": "string"  },  "pagination": {    "page": 0,    "page_size": 0,    "total_pages": 0,    "total_items": 0  }}
Response Codes & Statuses: Prembly API responses include custom response_code values (e.g., 00 Success, 01 Not Found, 02 Unavailable).
View Response Codes Guide
Prembly Slack Community

Join our developer Slack channel for real-time integration support, engineering updates, and direct Q&A with the Prembly team.

Join Slack Channel

Get request milestones GET

Returns the request's progress as a short list of milestones rather than every event — the view to drive a progress bar from. Fetch the timeline when you need the detail behind a milestone.

Get a request timeline GET

Returns the full event history for a candidate request — every status change, provider update and document received, oldest first. Use this to show progress. For the summarised view, fetch the milestones.