Submit Candidates for BGV (Bulk)

curl --request POST \
  --url https://bgv.konnectnxt.com/api/async/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"
    }
  ]
}
'

{
  "status": "success",
  "code": 200,
  "message": "BGV initiation+submission successful. Checks triggered asynchronously.",
  "data": {
    "recruiter_id": "781616b7-cb11-4888-8ee5-c15332438c12",
    "organization": "KonnectNXT DEV QA",
    "candidates_processed": 1,
    "total_cost": 5,
    "cases_created": [
      {
        "candidate_id": "049451228357439bb62cceed99345590",
        "case_id": "6649e5e1f32d4acea059acb265d1fe2b",
        "name": "Karan Narayan Patil"
      }
    ]
  },
  "errors": null,
  "credits_used": 5,
  "credits_remaining": 9962419
}

POST

async

bgv-submit

curl --request POST \
  --url https://bgv.konnectnxt.com/api/async/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"
    }
  ]
}
'

{
  "status": "success",
  "code": 200,
  "message": "BGV initiation+submission successful. Checks triggered asynchronously.",
  "data": {
    "recruiter_id": "781616b7-cb11-4888-8ee5-c15332438c12",
    "organization": "KonnectNXT DEV QA",
    "candidates_processed": 1,
    "total_cost": 5,
    "cases_created": [
      {
        "candidate_id": "049451228357439bb62cceed99345590",
        "case_id": "6649e5e1f32d4acea059acb265d1fe2b",
        "name": "Karan Narayan Patil"
      }
    ]
  },
  "errors": null,
  "credits_used": 5,
  "credits_remaining": 9962419
}

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 and validating the payload. You receive a webhook notification at your configured URL when each case reaches a terminal state.

Authorization

Every request must include your API key as a Bearer token:

Authorization: Bearer <your_api_key>

API keys are scoped to your organisation. Contact support to obtain or rotate a key.

BGV Lifecycle

POST /api/async/v2/bgv-submit/
          │
          ▼
  ┌──────────────┐
  │  Case Created │   ← cases_created[].case_id returned here
  └──────┬───────┘
         │  (async — checks run in the background)
         ▼
  ┌──────────────┐
  │  In Progress  │
  └──────┬───────┘
         │
         ▼
  ┌──────────────┐
  │  Completed   │   ← webhook fired: bgv.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 completes (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": "<YOUR_API_KEY>",
  "status": "completed"
}

On receiving this webhook, use the case_id to call the Report Download API and fetch the final report.

Request Structure

A request has two top-level arrays:

Field	Type	Required	Description
`checks`	array	Yes	One or more check keys to run for every candidate. At least one is required.
`candidates`	array	Yes	1–500 candidate objects. Every candidate must supply the fields required by the chosen checks.

The checks you list in checks are applied uniformly to all candidates. Each candidate must carry the fields required by those checks (see the tables below).

Supported Checks

Check Key	Description
`criminal_check`	Criminal / court record verification
`aml_check`	AML / sanctions / PEP / adverse-media screening
`credit_report_check`	Credit-bureau report (CIBIL / Experian)
`detailed_epfo_check`	EPFO (UAN) employment & PF history verification
`education_check`	Education qualification verification
`employment_verification_manual_check`	Manual employment verification via HR contact
`ref_check`	Reference check — referees contacted by email
`physical_address_check`	Physical (doorstep) address verification
`social_media_check`	Public digital / social-media footprint screening

Input Fields Per Check

For each check you request, the candidate object must carry the fields below. Date fields accept DD/MM/YYYY, DD-MM-YYYY or YYYY-MM-DD and must be past dates (unless noted). Phone numbers accept a bare 10-digit number or E.164 and are normalised to E.164.

`criminal_check`

Field	Type	Mandatory	Format / Rules	Example
`name`	string	Yes	Letters, spaces, hyphens, apostrophes, dots; min 2 chars	`Rahul Sharma`
`dob`	string	Yes	Date; must be a past date	`15-06-1992`
`permanent_address`	string	Yes*	Single string, min 10 chars. *May instead be a `Permanent` entry in `addresses`	`12, Nehru Nagar, Pune, Maharashtra, India - 411001`
`email`	string	No	Valid email	`rahul@example.com`
`phone`	string	No	10-digit or E.164	`+919876543210`
`father_name`	string	No	Free text	`Suresh Sharma`
`pincode`	string	No	Exactly 6 digits when present	`411001`
`city` / `state` / `country`	string	No	Free text (`country` defaults to `India`)	`Pune`

`aml_check`

Field	Type	Mandatory	Format / Rules	Example
`name`	string	Yes	Letters, spaces, hyphens, apostrophes, dots; min 2 chars	`Rahul Sharma`
`dob`	string	Yes	Date; must be past. Only the year is used for screening	`15-06-1992`
`email`	string	No	Valid email	`rahul@example.com`
`phone`	string	No	10-digit or E.164	`+919876543210`

`credit_report_check`

Field	Type	Mandatory	Format / Rules	Example
`name`	string	Yes	Letters, spaces, hyphens, apostrophes, dots; min 2 chars	`Rahul Sharma`
`dob`	string	Yes	Date; must be past	`15-06-1992`
`phone`	string	Yes	10-digit or E.164	`+919876543210`
`pan`	string	Yes	`AAAAA9999A` — 5 letters, 4 digits, 1 letter; upper-cased	`ABCDE1234F`
`addresses`	array	Yes	Non-empty list of address objects (see Address object). No duplicate `address_type`; `pincode` 4–10 digits	see below
`email`	string	No	Valid email	`rahul@example.com`
`country_code`	string	No	Digits only, defaults to `91`	`91`

`detailed_epfo_check`

Field	Type	Mandatory	Format / Rules	Example
`name`	string	Yes	Min 2 chars	`Rahul Sharma`
`uan_number`	string	Yes	Exactly 12 digits	`100000000001`
`dob`	string	No	Date; must be past	`15-06-1992`
`dont_have_uan`	boolean	No	`true` if the candidate has no UAN; default `false`	`false`
`email` / `phone`	string	No	Valid email / phone	`rahul@example.com`

`education_check`

Requires name and a non-empty education_details array. Each entry:

Field	Type	Mandatory	Format / Rules	Example
`course_type`	string	Yes	One of `10`, `12`, `GRADUATION`, `UNDERGRAD`, `POSTGRAD`, `PHD`, `OTHER` (`GRADUATION` → `UNDERGRAD`)	`UNDERGRAD`
`university_name`	string	Yes	Non-blank	`Bangalore University`
`degree_name`	string	Yes	Non-blank	`Bachelor of Engineering`
`registration_number`	string	Yes	Non-blank	`BU2018CS001`
`education_proof`	string (URL)	Yes	URL ending in `.pdf`, `.jpg`, `.jpeg` or `.png`	`https://.../degree.pdf`
`college`	string	Yes	Non-blank	`RV College of Engineering`
`specialization`	string	Yes	Non-blank	`Computer Science`
`date_of_joining`	string	Yes	Date	`01-08-2014`
`date_of_completion`	string	No	Date; blank = still studying	`30-05-2018`
`consolidated_mark_sheet`	string (URL)	No	Same URL rules as `education_proof`	`https://.../marksheet.pdf`

`employment_verification_manual_check`

Requires name and a non-empty employment_details array. Each entry:

Field	Type	Mandatory	Format / Rules	Example
`employer_name`	string	Yes	Non-blank	`Infosys Limited`
`designation`	string	Yes	Non-blank	`Software Engineer`
`salary`	string	Yes	Amount as string	`80000`
`start_date`	string	Yes	Date (no 2-digit years)	`01-07-2019`
`end_date`	string	Conditional	Required when `is_currently_working` is `false`; cleared when `true`	`30-06-2022`
`is_currently_working`	boolean	No	Defaults to `false`	`false`
`hr_name`	string	Yes	HR / manager full name	`Priya Iyer`
`hr_email`	string	Yes	Valid email	`priya.iyer@infosys.com`
`employee_id`	string	No	Staff ID	`INF2019001`
`hr_phone` / `hr_whatsapp_number`	string	No	10-digit or E.164	`+919123456780`
`hr_designation`	string	No	HR job title	`HR Executive`

`ref_check`

Requires name and a non-empty reference_details array. Each employer block:

Field	Type	Mandatory	Format / Rules	Example
`employer_name`	string	Yes	Non-blank	`Infosys`
`start_date`	string	Yes	Date	`01-07-2019`
`end_date`	string	Conditional	Required unless `is_currently_working` is `true`	`30-06-2022`
`is_currently_working`	boolean	No	Defaults to `false`	`false`
`references`	array	Yes	Non-empty list of referees, each with `name` + `email` (referee `phone`, `designation`, `whatsapp_number` optional)	see below
`designation` / `employee_id`	string	No	Candidate’s role / ID at this employer	`Software Engineer`

`physical_address_check`

Requires name, email, phone and a non-empty addresses array. One verification runs per address entry.

`social_media_check`

Field	Type	Mandatory	Format / Rules	Example
`name`	string	Yes	Candidate full name	`Rahul Sharma`
`email`	string	Yes	Valid email	`rahul@example.com`
`current_employer`	string	Yes	Non-blank	`Wipro Technologies`
`current_designation`	string	Yes	Non-blank	`Senior Software Engineer`
`highest_education`	string	Yes	Free text	`B.Tech Computer Science`
`mother_name`	string	Yes	Non-blank	`Sunita Sharma`
`doc_urls`	array	Yes	Non-empty list of `{label, url}` objects; `label` non-blank, `url` valid	see below
`address_type`	string	Yes	`Current` or `Permanent`; top-level or `addresses[0].address_type`	`Current`
`dob` / `phone` / `gender` / `father_name` / `secondary_email` / `secondary_phone`	string	No	Standard formats	`Male`

Address object

Used by credit_report_check, physical_address_check, and (for address_type) social_media_check. Each candidate may submit at most one Current and one Permanent address.

Field	Type	Mandatory	Format / Rules	Example
`address_type`	string	Yes	`Current` or `Permanent`; unique per candidate	`Current`
`street` or `address`	string	Yes	At least one non-blank doorstep line	`12, MG Road, Sector 4`
`city`	string	Cond.	Mandatory (2–100 chars) for `physical_address_check`; optional otherwise	`Bengaluru`
`state`	string	Cond.	Same rule as `city`	`Karnataka`
`country`	string	Cond.	Same rule as `city`; defaults to `India`	`India`
`pincode`	string	Cond.	6 digits for `physical_address_check`; 4–10 digits for `credit_report_check`	`560001`
`landmark`	string	No	≤ 200 chars	`Opposite City Mall`
`landline_no`	string	No	6–15 digits (optional `+`, spaces, hyphens)	`080-4123 4567`
`residence_type`	string	No	`Owned`, `Rented`, `PG`, `Hostel`, `Company Provided`	`Owned`
`period_of_stay_from` / `period_of_stay_to`	string	No	`DD/MM/YYYY`, `DD-MM-YYYY`, `YYYY-MM-DD`, `MM/YYYY` or `YYYY-MM`; `to` ≥ `from`	`01/2015`

Responses

On success the API returns the created cases. Use each case_id to track the case and download its report.

{
  "success": true,
  "message": "BGV initiation+submission successful. Checks triggered asynchronously.",
  "data": {
    "recruiter_id": "abc123def456",
    "organization": "Acme Corp",
    "candidates_processed": 1,
    "total_cost": 50.0,
    "cases_created": [
      {
        "candidate_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
        "case_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
        "name": "Rahul Sharma",
        "email": "rahul.sharma@example.com"
      }
    ]
  }
}

Error responses

Status	Meaning
`400`	Validation failed — missing/empty `candidates` or `checks`, unknown check key, or a candidate missing/invalid a required field. The message identifies the candidate index and the offending field(s).
`402`	Insufficient credits to cover the request.
`403`	One or more requested checks are not enabled for your account.
`500`	Internal server error.

Validation error (example):

{
  "success": false,
  "message": "Candidate at index 0 missing required fields for requested checks: {\"criminal_check\": [\"permanent_address\"]}"
}

Notes

Maximum 500 candidates per request.
If any candidate (or any nested entry within a candidate) fails validation, the entire request is rejected — there are no partial submissions.
case_id and candidate_id in the response are the same 32-character hex value.

Authorizations

Authorization

string

header

required

API key issued by KonnectNXT. Pass as Authorization: Bearer <your_api_key>.

Body

application/json

checks

enum<string>[]

required

List of check types to run for every candidate in this request. At least one check must be provided. Unknown keys are rejected with a 400.

Minimum array length: 1

Available options:

criminal_check,

aml_check,

credit_report_check,

detailed_epfo_check,

education_check,

employment_verification_manual_check,

ref_check,

physical_address_check,

social_media_check

Example:

["criminal_check", "aml_check"]

candidates

object[]

required

Array of candidate objects. Maximum 500 candidates per request. Every candidate must supply the fields required by the checks listed in checks.

Required array length: 1 - 500 elements

Show child attributes

Response

Candidates accepted, checks triggered asynchronously

status

enum<string>

Available options:

success

Example:

"success"

code

integer

Example:

200

message

string

Example:

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

data

object

Show child attributes

errors

any | null

Always null on a successful response.

Example:

null

credits_used

number

Credits consumed by this submission.

Example:

5

credits_remaining

number

Credits remaining in the organisation account after this submission.

Example:

9962419

API Documentation

Background Verification

Lookup APIs

Financial APIs

Vehicle APIs

OCR APIs

Masking APIs

Validation

Business Verification

Document E-Sign

Global DB

Credits

Submit Candidates for BGV (Bulk)

Overview

Authorization

BGV Lifecycle

Webhook Notification

Request Structure

Supported Checks

Input Fields Per Check

`criminal_check`

`aml_check`

`credit_report_check`

`detailed_epfo_check`

`education_check`

`employment_verification_manual_check`

`ref_check`

`physical_address_check`

`social_media_check`

Address object

Responses

Error responses

Notes

Authorizations

Body

Response

​Overview

​Authorization

​BGV Lifecycle

​Webhook Notification

​Request Structure

​Supported Checks

​Input Fields Per Check

​criminal_check

​aml_check

​credit_report_check

​detailed_epfo_check

​education_check

​employment_verification_manual_check

​ref_check

​physical_address_check

​social_media_check

​Address object

​Responses

​Error responses

​Notes

Authorizations

Body

Response

Overview

Authorization

BGV Lifecycle

Webhook Notification

Request Structure

Supported Checks

Input Fields Per Check

`criminal_check`

`aml_check`

`credit_report_check`

`detailed_epfo_check`

`education_check`

`employment_verification_manual_check`

`ref_check`

`physical_address_check`

`social_media_check`

Address object

Responses

Error responses

Notes