Background Verification
The Background Verification (BGV) API suite lets you run structured verification workflows for candidates — covering education, employment, address, criminal records, and more.
How It Works
1. Create a Form
A form defines which verification checks are required for a candidate. You configure this once and reuse the form for multiple candidates.
{
"name": "Engineering Hire",
"verifications": [
{ "name": "bgv-employment", "skipAllowed": false },
{ "name": "bgv-degree", "skipAllowed": true }
]
}
The response includes a _id (form ID) that you pass when adding a candidate.
2. Add a Candidate
Submit the candidate's basic information along with the form ID from Step 1. This creates a transaction and returns a transactionId.
3. Upload Documents & Submit Verifications
For each check in the form, upload the relevant document using the File Upload API to get a fileUrl, then submit the verification details.
File Upload → · Education · Employment · Address · Criminal & Police
4. Receive Webhook Notifications
Once all verifications are completed, Trential sends a webhook notification to your configured endpoint. Configure a webhook once and it applies to all transactions.
5. Retrieve Results & Download Report
When you receive the webhook, use the transactionId to fetch the verification data or download the final PDF report.
Transaction Info → · Verification Info → · Download Report →
Sequence of APIs
| Step | API |
|---|---|
| 1 | Get Purpose (optional — call once to get the purpose ID for your use case) |
| 2 | Create Form |
| 3 | Create Profile (uses form ID) |
| 4 | Upload File |
| 5 | Initiate verifications — Education, Employment, Address, etc. |
| 6 | Receive webhook (see below) — verification-completed or insufficiency-raised |
| 6a | (if insufficiency) Resolve Insufficiency and wait for insufficiency-resolved webhook |
| 7 | Transaction Info / Verification Info |
| 8 | Download Report |
Configuring Webhooks
Register a URL where Trential will POST a notification when a transaction is completed.
Endpoint: POST https://api.trential.dev/verification/api/1.0/webhook-config
Request
{
"endpoint": "https://your-server.com/webhook",
"apiKey": "your-shared-secret",
"description": "BGV completion notifications"
}
| Field | Required | Description |
|---|---|---|
endpoint | Yes | The URL Trential will POST the notification to |
apiKey | Yes | A secret string you choose. Trential sends it back in the x-webhook-key header so you can verify the request is genuine. |
description | No | A label for this webhook configuration |
Webhook Payloads
Trential POSTs to your endpoint with Content-Type: application/json. There are two payload shapes depending on scope.
Transaction-level event
Fired when the overall transaction changes state (e.g. all verifications complete).
{
"transactionId": "664758ec4c1572facafdafa0",
"orgId": "65940bdb9b271d7e123a90cc",
"action": "transaction-completed",
"verificationReportUrl": "https://storage.googleapis.com/trential-reports/...",
"scope": "transaction"
}
| Field | Description |
|---|---|
transactionId | The BGV transaction ID |
orgId | Your organisation ID |
action | transaction-completed · transaction-closed · evaluation-completed |
verificationReportUrl | Signed URL to the full PDF report (present when action is transaction-completed) |
scope | Always transaction for this shape |
Verification-level event
Fired each time an individual verification within the transaction changes state.
{
"transactionId": "664758ec4c1572facafdafa0",
"verificationId": "b8017572-06b6-46d5-8155-a36006f75f23",
"orgId": "65940bdb9b271d7e123a90cc",
"action": "verification-completed",
"scope": "verification"
}
| Field | Description |
|---|---|
transactionId | The BGV transaction ID |
verificationId | The sub-type ID of the specific verification |
orgId | Your organisation ID |
action | verification-started · verification-completed · verification-failed · insufficiency-raised · insufficiency-resolved · verification-closed |
scope | Always verification for this shape |
Verifying Webhook Payloads
Every webhook request from Trential includes:
x-webhook-key: your-shared-secret
Validate this header against the apiKey you registered before processing the payload.
Managing Webhooks
| Action | API |
|---|---|
| List all webhooks | Fetch Webhook Configurations |
| Update a webhook | Update Webhook Configuration |
| Delete a webhook | Delete Webhook Configuration |