BGCHECK: Background Check
A structured background / compliance check record attached to a candidate and optionally a placement.
Default definition. This article describes the default
BGCHECK definition shipped with DemandFlow. Administrators can add, remove, rename, or re-type fields, change which ones are required, and alter the layout from the Definitions screen in Settings. Your tenant's current schema may differ from what is shown here. To read the current definition at any time, GET the DEFINITION object whose id matches BGCHECK.Entity properties
| Property | Value |
|---|---|
| Entity code | BGCHECK |
| Display name | Background Check |
| Plural | Background Checks |
| Level | 11020 |
Computed name | {{checkType}} . {{candidate}} |
Use cases
BGCHECK replaces the free-form compliance checkboxes previously held on PLACE (creditChecked, idLogged, referenceReceived) with a typed record per check. Each record captures the check type (DBS, credit, right-to-work, reference, qualification, etc.), provider, lifecycle status (requested → in progress → passed/failed/expired), dates and certificate reference. BGCHECK is a child of CANDIDATE via comboKey (SUB|CANDIDATE|ENT:), so checks live with the person and persist across placements.
Fields
General: Check
| Field | Type | Required | Notes |
|---|---|---|---|
name | text | Read-only. Auto-composed from check type and candidate | |
candidate | reference → CANDIDATE | Yes | Candidate. |
placement | reference → PLACE | Optional. link this check to a specific placement | |
checkType | enum | Yes | Check type. Valid ids: dbsBasic (DBS. Basic), dbsStandard (DBS. Standard), dbsEnhanced (DBS. Enhanced), credit (Credit), rightToWork (Right to Work), identity (Identity), reference (Reference), qualification (Qualification), profRegistration (Professional Registration), profIndemnity (Professional Indemnity), publicLiability (Public Liability), medical (Medical), other (Other). |
status | enum | Yes | Status. Valid ids: notRequired (Not Required), requested (Requested), inProgress (In Progress), passed (Passed), failed (Failed), expired (Expired), cancelled (Cancelled). |
provider | text | Who performed the check (e.g. DBS, Experian, referee name) | |
certificateRef | text | Certificate number or reference provided by the check provider |
General: Dates
| Field | Type | Required | Notes |
|---|---|---|---|
requestedDate | date | Requested. | |
completedDate | date | Completed. | |
expiryDate | date | Date the check expires and needs to be renewed | |
owner | reference → user | Owner. |
General: Notes
| Field | Type | Required | Notes |
|---|---|---|---|
notes | text (multi-line) | Notes. |
Attachments
| Field | Panel | Allowed types | Max files |
|---|---|---|---|
checkDocuments | Documents | pdf, doc, docx, xls, xlsx, png, jpg, jpeg, msg, eml | multiple |
Relationships
- Lookups:
candidatepoints at aCANDIDATErecord;placementpoints at aPLACErecord. - Activity: activity timeline panel attached.
Creating a Background Check via the API
POST /v1/objects
Authorization: Bearer <your-pat>
Content-Type: application/json
{
"entity": "BGCHECK",
"level": 11020,
"comboKey": "SUB:<your-sub-id>|ENT:",
"candidate": "",
"checkType": "dbsBasic",
"status": "notRequired",
"name": "Reference"
} Listing Background Checks records
GET /v1/entities/BGCHECK/SUB