Skip to main content
POST
/
recruiter
/
v2
/
bgv-submit
curl --request POST \ --url https://bgv.konnectnxt.com/api/recruiter/v2/bgv-submit/ \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "checks": [ "criminal_check", "aml_check" ], "candidates": [ { "name": "Ravi Kumar", "dob": "1990-05-15", "permanent_address": "12, MG Road, Indiranagar, Bengaluru, Karnataka 560038" } ] } '
{ "success": true, "message": "BGV initiation+submission successful. Checks triggered asynchronously.", "data": { "recruiter_id": "abc123def456", "organization": "Acme Corp", "candidates_processed": 1, "total_cost": 125, "cases_created": [ { "candidate_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "case_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "name": "Ravi Kumar", "email": "ravi.kumar@example.com" } ] } }

​
Overview

Submit one or more candidates for background verification in a single API call. The platform creates a BGV case for each candidate and triggers all requested checks asynchronously — the API returns immediately after accepting the payload. You will receive a webhook notification at your configured URL when each case reaches a terminal state (completed or rejected).

​
BGV Lifecycle

POST /api/recruiter/v2/bgv-submit/
          │
          ▼
  ┌──────────────┐
  │  Case Created │   ← cases_created[].case_id returned here
  └──────┬───────┘
         │  (async — checks run in background)
         ▼
  ┌──────────────┐
  │  In Progress  │
  └──────┬───────┘
         │
         ▼
  ┌──────────────┐
  │  Completed   │   ← webhook fired: case.completed
  └──────────────┘
Use the case_id from the response to download the final report via the BGV Report Download endpoint.

​
Webhook Notification

When a case is completed (all requested checks are processed), a POST request is sent to your configured webhook URL. The payload includes the case_id so you can map it back to the candidate you submitted. Webhook payload (example): 
{
  "candidate": {
    "email": "priya@example.com",
    "id": "894bf8c549654ea586286733c4d31db3",
    "name": "Priya Sharma"
  },
  "report_url": "<FILE_URL>",
  "case_id": "8a4d5a09b75e41dda935f3f41fc6cbae",
  "completed_at": "2026-06-04T13:38:45.577049+00:00",
  "event": "bgv.case.completed",
  "org_id": "8ab03388b94a4d03ac8952f63019aba1",
  "status": "completed"
}
On receiving this webhook, use the case_id to call the Report Download API and fetch the final report.

​
Supported Checks

Check KeyDescription
criminal_checkCourt records & criminal history screening
aml_checkGlobal database / AML / sanctions / PEP screening
credit_report_checkFull credit bureau report (CIBIL / Experian)

​
Required Fields Per Check

CheckRequired Candidate Fields
criminal_checkname, dob, permanent_address
aml_checkname, dob
credit_report_checkname, dob, phone, pan
All other fields (email, father_name, etc.) are optional but improve match accuracy.

​
Notes

  • Maximum 500 candidates per request.
  • Credits are deducted upfront at submission. The exact cost depends on the checks requested and your plan/bundle.
  • If any candidate fails validation the entire request is rejected — no partial submissions.
  • case_id and candidate_id in the response are the same UUID value.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
checks
enum<string>[]
required

List of check types to run for every candidate. At least one check must be provided.

Minimum array length: 1
Available options:
criminal_check,
aml_check,
credit_report_check
Example:
["criminal_check", "aml_check"]
​
candidates
object[]
required

Array of candidate objects. Maximum 500 candidates per request.

Required array length: 1 - 500 elements
​
bundle_id
string

Optional ID of a pre-configured bundle package for bundle-level pricing.

Example:

"bundle_abc123"

Response

Candidates accepted, checks triggered asynchronously

​
success
boolean
Example:

true

​
message
string
Example:

"BGV initiation+submission successful. Checks triggered asynchronously."

​
data
object