Prembly
GuidesAPI Reference
Background ChecksRequestsCancel a candidate request POST
POST
/api/v1/api/bgc/requests/candidates/{reference}/cancel/

Cancels a request before a provider has picked it up.

Allowed only while the status is pending or pending_payment and no verification_id has been assigned. Once a provider has started work the request can no longer be cancelled and this returns 409.

The candidate is never notified of a cancellation.

Authorization

ApiKeyAuth
X-API-Key<token>

In: header

Path Parameters

reference*string

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

Formatuuid

Request Body

TypeScript Definitions

Use the request body type in TypeScript.

Serializer for cancelling a candidate request before partner pickup.

Response Body

application/json

curl -X POST "https://example.com/api/v1/api/bgc/requests/candidates/497f6eca-6276-4993-bfeb-53cbbbba6f08/cancel/" \  -H "Content-Type: application/json" \  -d '{}'
{  "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 a candidate request GET

Returns a single candidate request, including its current status, the package and check types attached to it, and the candidate's submitted details where the form has been completed.

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.