> ## Documentation Index > Fetch the complete documentation index at: https://docs.konnectnxt.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit Candidates for BGV (Bulk) > Submit one or more candidates for background verification. The checks listed in `checks` run asynchronously for every candidate; the response returns a `case_id` per candidate. See the page text for the full per-check field reference. ## 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 ``` 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](/api-reference/bgv/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):** ```json theme={null} { "candidate": { "email": "priya@example.com", "id": "894bf8c549654ea586286733c4d31db3", "name": "Priya Sharma" }, "report_url": "", "case_id": "8a4d5a09b75e41dda935f3f41fc6cbae", "completed_at": "2026-06-04T13:38:45.577049+00:00", "event": "bgv.case.completed", "org_id": "", "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](#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. ```json theme={null} { "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):** ```json theme={null} { "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. ## OpenAPI ````yaml POST /async/v2/bgv-submit/ openapi: 3.0.0 info: title: KonnectNXT API Store description: >- A sample API that uses a plant store as an example to demonstrate features in the OpenAPI specification license: name: MIT version: 1.0.0 servers: - url: https://bgv.konnectnxt.com/api description: Production - url: https://testbgv.konnectnxt.com/api description: QA security: - bearerAuth: [] paths: /async/v2/bgv-submit/: post: tags: - BGV Submit V2 summary: Submit Candidates for BGV (Bulk) description: >- Submit one or more candidates for background verification. The checks listed in `checks` run asynchronously for every candidate; the response returns a `case_id` per candidate. See the page text for the full per-check field reference. operationId: bgvSubmitV2 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BGVSubmitV2Request' examples: criminal_and_aml: summary: Criminal + AML check value: checks: - criminal_check - aml_check candidates: - name: Ravi Kumar dob: '1990-05-15' permanent_address: 12, MG Road, Indiranagar, Bengaluru, Karnataka 560038 credit_report: summary: Credit report check (requires PAN + addresses) value: checks: - credit_report_check candidates: - name: Amit Verma dob: '1985-11-20' phone: '9876543210' pan: ABCPV1234D addresses: - address_type: Current street: 12, MG Road, Sector 4 city: Bengaluru state: Karnataka country: India pincode: '560001' epfo_check: summary: Detailed EPFO check (UAN) value: checks: - detailed_epfo_check candidates: - name: Rahul Sharma uan_number: '100000000001' dob: 15-06-1992 education_check: summary: Education verification value: checks: - education_check candidates: - name: Rahul Sharma education_details: - course_type: UNDERGRAD university_name: Bangalore University degree_name: Bachelor of Engineering registration_number: BU2018CS001 education_proof: https://storage.example.com/docs/degree.pdf college: RV College of Engineering specialization: Computer Science date_of_joining: 01-08-2014 date_of_completion: 30-05-2018 employment_check: summary: Manual employment verification value: checks: - employment_verification_manual_check candidates: - name: Rahul Sharma email: rahul.sharma@example.com phone: '+919876543210' employment_details: - employer_name: Infosys Limited designation: Software Engineer employee_id: INF2019001 salary: '80000' start_date: 01-07-2019 end_date: 30-06-2022 is_currently_working: false hr_name: Priya Iyer hr_email: priya.iyer@infosys.com hr_phone: '+919123456780' reference_check: summary: Reference check value: checks: - ref_check candidates: - name: Rahul Sharma email: rahul.sharma@example.com phone: '+919876543210' reference_details: - employer_name: Infosys designation: Software Engineer start_date: 01-07-2019 end_date: 30-06-2022 is_currently_working: false references: - name: Kavita Nair email: kavita.nair@infosys.com phone: '9111222333' designation: Team Lead physical_address_check: summary: Physical (doorstep) address verification value: checks: - physical_address_check candidates: - name: Rahul Sharma email: rahul@example.com phone: '+919876543210' addresses: - address_type: Current street: 12, MG Road, Sector 4 city: Bengaluru state: Karnataka country: India pincode: '560001' social_media_check: summary: Social media footprint screening value: checks: - social_media_check candidates: - name: Rahul Sharma email: rahul@example.com phone: '+919876543210' mother_name: Sunita Sharma current_employer: Wipro Technologies current_designation: Senior Software Engineer highest_education: B.Tech Computer Science addresses: - address_type: Current city: Pune state: Maharashtra country: India pincode: '411001' doc_urls: - label: Aadhaar Card url: https://storage.example.com/docs/aadhaar.jpg responses: '200': description: Candidates accepted, checks triggered asynchronously content: application/json: schema: $ref: '#/components/schemas/BGVSubmitV2Response' examples: Success: summary: Successful submission value: 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 '400': description: Bad request — missing/invalid fields or unknown check keys content: application/json: schema: $ref: '#/components/schemas/BGVSubmitV2ErrorResponse' examples: missing_candidates: summary: Missing candidates array value: status: error code: 400 message: Invalid or missing 'candidates' array. data: null errors: Invalid or missing 'candidates' array. credits_used: null credits_remaining: null missing_field: summary: Required field missing for a check value: status: error code: 400 message: >- Candidate at index 0 missing required fields for requested checks: {"criminal_check": ["permanent_address"]} data: null errors: criminal_check: - permanent_address credits_used: null credits_remaining: null invalid_pan: summary: PAN format invalid value: status: error code: 400 message: >- Candidate at index 0: PAN number must match format ABCDE1234F. data: null errors: >- Candidate at index 0: PAN number must match format ABCDE1234F. credits_used: null credits_remaining: null '402': description: Insufficient credits in the organisation account content: application/json: schema: $ref: '#/components/schemas/BGVSubmitV2ErrorResponse' examples: InsufficientCredits: summary: Not enough credits value: status: error code: 402 message: 'Insufficient credits. Required: 500, Available: 200' data: null errors: 'Insufficient credits. Required: 500, Available: 200' credits_used: null credits_remaining: null '403': description: One or more requested checks are not enabled for your account content: application/json: schema: $ref: '#/components/schemas/BGVSubmitV2ErrorResponse' examples: CheckNotEnabled: summary: Check not enabled for account value: status: error code: 403 message: >- The following checks are not enabled for your account: ['credit_report_check']. Please contact support to enable them. data: null errors: >- The following checks are not enabled for your account: ['credit_report_check']. Please contact support to enable them. credits_used: null credits_remaining: null '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/BGVSubmitV2ErrorResponse' examples: ServerError: summary: Internal server error value: status: error code: 500 message: >- An unexpected error occurred. Please try again later or contact support. data: null errors: >- An unexpected error occurred. Please try again later or contact support. credits_used: null credits_remaining: null security: - bearerAuth: [] components: schemas: BGVSubmitV2Request: type: object required: - checks - candidates properties: checks: type: array description: >- 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. minItems: 1 items: type: string enum: - 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: type: array description: >- Array of candidate objects. Maximum 500 candidates per request. Every candidate must supply the fields required by the checks listed in `checks`. minItems: 1 maxItems: 500 items: $ref: '#/components/schemas/BGVCandidateInput' BGVSubmitV2Response: type: object properties: status: type: string enum: - success example: success code: type: integer example: 200 message: type: string example: >- BGV initiation+submission successful. Checks triggered asynchronously. data: type: object properties: recruiter_id: type: string description: ID of the authenticated recruiter. example: 781616b7-cb11-4888-8ee5-c15332438c12 organization: type: string description: Name of the organisation. example: Acme Corp candidates_processed: type: integer description: Number of candidates successfully submitted. example: 1 total_cost: type: number format: float description: Total credits deducted for this submission. example: 125 cases_created: type: array description: >- List of cases created — one per candidate, in the same order as the input array. items: type: object properties: candidate_id: type: string example: 049451228357439bb62cceed99345590 case_id: type: string example: 6649e5e1f32d4acea059acb265d1fe2b name: type: string example: Ravi Kumar email: type: string example: ravi.kumar@example.com errors: nullable: true example: null description: Always null on a successful response. credits_used: type: number description: Credits consumed by this submission. example: 5 credits_remaining: type: number description: Credits remaining in the organisation account after this submission. example: 9962419 BGVSubmitV2ErrorResponse: type: object properties: status: type: string enum: - error example: error code: type: integer example: 400 message: type: string description: Human-readable description of the error. example: Invalid or missing 'candidates' array. data: type: object nullable: true example: null errors: description: Detailed error information, or null if none. nullable: true oneOf: - type: string - type: object credits_used: type: number nullable: true example: null credits_remaining: type: number nullable: true example: null BGVCandidateInput: type: object description: >- Candidate data. Which fields are required depends on the checks requested — see the per-check field tables in the endpoint description. Fields not required by any requested check are optional but may be supplied for richer records. properties: name: type: string description: >- Full legal name. Letters, spaces, hyphens, apostrophes and dots only; min 2 characters. Required for every check. minLength: 2 example: Rahul Sharma dob: type: string description: >- Date of birth. Accepted formats: `DD/MM/YYYY`, `DD-MM-YYYY` or `YYYY-MM-DD`. Must be a past date. Required for `criminal_check`, `aml_check` and `credit_report_check`; optional for the others. example: 15-06-1992 email: type: string format: email description: >- Candidate's email address. Required for `physical_address_check` and `social_media_check`; optional otherwise. example: rahul@example.com phone: type: string description: >- Mobile number — bare 10-digit (`9876543210`) or E.164 (`+919876543210`); normalised to E.164. Required for `credit_report_check` and `physical_address_check`. example: '+919876543210' country_code: type: string description: Numeric country code without `+`. Defaults to `91` (India). default: '91' example: '91' pan: type: string description: >- PAN number. Format `AAAAA9999A` — 5 uppercase letters, 4 digits, 1 uppercase letter (upper-cased before validation). Required for `credit_report_check`. pattern: ^[A-Z]{5}[0-9]{4}[A-Z]$ example: ABCDE1234F permanent_address: type: string description: >- Permanent address as a single string, min 10 characters. Required for `criminal_check` (unless supplied as a `Permanent` entry inside `addresses`). minLength: 10 example: 12, Nehru Nagar, Pune, Maharashtra, India - 411001 father_name: type: string description: Father's full name. Optional; improves criminal-check accuracy. example: Suresh Sharma city: type: string description: City of residence. Optional. example: Pune state: type: string description: State of residence. Optional. example: Maharashtra pincode: type: string description: >- PIN code. When present for `criminal_check`, must be exactly 6 digits. example: '411001' country: type: string description: Country of residence. Defaults to `India`. default: India example: India uan_number: type: string description: >- Universal Account Number — exactly 12 digits. Required for `detailed_epfo_check`. example: '100000000001' dont_have_uan: type: boolean description: >- Set `true` when the candidate has no UAN (used by `detailed_epfo_check`). Defaults to `false`. default: false addresses: type: array description: >- List of address objects. **Required** (non-empty) for `credit_report_check` and `physical_address_check`. For `criminal_check`/`social_media_check` an entry here can supply the permanent address / `address_type`. No two entries may share the same `address_type`. items: $ref: '#/components/schemas/BGVAddressEntry' education_details: type: array description: >- Non-empty list of education entries. **Required** for `education_check`. items: $ref: '#/components/schemas/BGVEducationEntry' employment_details: type: array description: >- Non-empty list of employment entries. **Required** for `employment_verification_manual_check`. items: $ref: '#/components/schemas/BGVEmploymentEntry' reference_details: type: array description: >- Non-empty list of employer blocks, each with referees to contact. **Required** for `ref_check`. items: $ref: '#/components/schemas/BGVReferenceBlock' doc_urls: type: array description: >- Non-empty list of supporting-document `{label, url}` objects. **Required** for `social_media_check`. items: $ref: '#/components/schemas/BGVDocUrlEntry' current_employer: type: string description: Current company name. Required for `social_media_check`. example: Wipro Technologies current_designation: type: string description: Current job title. Required for `social_media_check`. example: Senior Software Engineer highest_education: type: string description: >- Highest qualification (free text). Required for `social_media_check`. example: B.Tech Computer Science mother_name: type: string description: Candidate's mother's name. Required for `social_media_check`. example: Sunita Sharma gender: type: string description: Candidate gender. Optional (used by `social_media_check`). example: Male address_type: type: string enum: - Current - Permanent description: >- Address category for `social_media_check`. Supply here at top level, or as `addresses[0].address_type`. example: Current secondary_email: type: string format: email description: Optional secondary email (used by `social_media_check`). example: rahul.personal@gmail.com secondary_phone: type: string description: Optional secondary phone (used by `social_media_check`). example: '+919000011122' BGVAddressEntry: type: object description: >- A single address entry. Validation strictness depends on the check (`physical_address_check` is strictest; `credit_report_check` allows a 4–10 digit pincode and free-text optional fields). required: - address_type properties: address_type: type: string enum: - Current - Permanent description: Address category. Each value may appear at most once per candidate. example: Current street: type: string description: >- Primary doorstep / street line. Required unless `address` is supplied. example: 12, MG Road, Sector 4 address: type: string description: >- Alternative doorstep line. Copied into `street` when `street` is blank. example: Flat 4, Green Apartments, Baner city: type: string description: >- City. Mandatory and 2–100 chars for `physical_address_check`; optional for `credit_report_check`. example: Bengaluru state: type: string description: State. Same rules as `city`. example: Karnataka country: type: string description: Country. Defaults to `India`. default: India example: India pincode: type: string description: >- PIN code. Exactly 6 digits for `physical_address_check`; 4–10 digits (when present) for `credit_report_check`. example: '560001' landmark: type: string description: Optional nearby landmark (≤ 200 chars). example: Opposite City Mall landline_no: type: string description: Optional landline (6–15 digits; `+`, spaces, hyphens allowed). example: 080-4123 4567 residence_type: type: string description: >- Optional ownership / tenancy type. For `physical_address_check`: `Owned`, `Rented`, `PG`, `Hostel`, `Company Provided`. example: Owned referee: type: string description: Optional name of someone who can confirm residence (≤ 100 chars). example: Neighbour Singh period_of_stay_from: type: string description: >- Optional tenure start. `DD/MM/YYYY`, `DD-MM-YYYY`, `YYYY-MM-DD`, `MM/YYYY` or `YYYY-MM`. example: 01/2015 period_of_stay_to: type: string description: Optional tenure end (must be ≥ `period_of_stay_from`). example: 12/2022 BGVEducationEntry: type: object description: A single education qualification entry for `education_check`. required: - course_type - university_name - degree_name - registration_number - education_proof - college - specialization - date_of_joining properties: course_type: type: string enum: - '10' - '12' - GRADUATION - UNDERGRAD - POSTGRAD - PHD - OTHER description: >- Level of education. `GRADUATION` is accepted and normalised to `UNDERGRAD`. example: UNDERGRAD university_name: type: string description: Awarding university or board (non-blank). example: Bangalore University degree_name: type: string description: Degree / qualification awarded (non-blank). example: Bachelor of Engineering registration_number: type: string description: Enrollment / registration number (non-blank). example: BU2018CS001 education_proof: type: string format: uri description: >- URL of the degree certificate. Must end in `.pdf`, `.jpg`, `.jpeg` or `.png`. example: https://storage.example.com/docs/degree.pdf college: type: string description: College / institution attended (non-blank). example: RV College of Engineering specialization: type: string description: Branch / major (non-blank). example: Computer Science date_of_joining: type: string description: Course start date. `DD/MM/YYYY`, `DD-MM-YYYY` or `YYYY-MM-DD`. example: 01-08-2014 date_of_completion: type: string description: Completion date. Blank = still studying. example: 30-05-2018 consolidated_mark_sheet: type: string format: uri description: >- Optional consolidated mark sheet URL (same extension rules as `education_proof`). example: https://storage.example.com/docs/marksheet.pdf BGVEmploymentEntry: type: object description: A single employment entry for `employment_verification_manual_check`. required: - employer_name - designation - salary - start_date - hr_name - hr_email properties: employer_name: type: string description: Full legal name of the employer. example: Infosys Limited designation: type: string description: Job title held at this employer. example: Software Engineer salary: type: string description: Salary amount (as a string). example: '80000' start_date: type: string description: >- Join date. `DD/MM/YYYY`, `DD-MM-YYYY` or `YYYY-MM-DD` (no 2-digit years). example: 01-07-2019 end_date: type: string description: >- Leave date. Required when `is_currently_working` is `false`; cleared when `true`. example: 30-06-2022 is_currently_working: type: boolean description: Whether the candidate still works here. Defaults to `false`. default: false hr_name: type: string description: HR contact / reporting manager name. example: Priya Iyer hr_email: type: string format: email description: HR contact email (valid email). example: priya.iyer@infosys.com employee_id: type: string description: Optional staff ID. example: INF2019001 hr_designation: type: string description: Optional HR job title. example: HR Executive hr_phone: type: string description: Optional HR phone (10-digit or E.164). example: '+919123456780' hr_whatsapp_number: type: string description: Optional HR WhatsApp number. example: '+919123456780' BGVReferenceBlock: type: object description: >- One employer block for `ref_check`, carrying tenure context and a list of referees to contact. required: - employer_name - start_date - references properties: employer_name: type: string description: Employer being referenced (non-blank). example: Infosys start_date: type: string description: Tenure start. `DD/MM/YYYY`, `DD-MM-YYYY` or `YYYY-MM-DD`. example: 01-07-2019 end_date: type: string description: Tenure end. Required unless `is_currently_working` is `true`. example: 30-06-2022 is_currently_working: type: boolean description: Whether the candidate still works here. Defaults to `false`. default: false designation: type: string description: Candidate's role at this employer. example: Software Engineer employee_id: type: string description: Candidate's employee / staff ID. example: INF2019001 references: type: array description: >- Referees to contact for this employer. At least one entry, each with `name` and `email`. minItems: 1 items: $ref: '#/components/schemas/BGVReferenceContact' BGVDocUrlEntry: type: object description: A supporting-document reference for `social_media_check`. required: - label - url properties: label: type: string description: Human-readable label (non-blank). example: Aadhaar Card url: type: string format: uri description: Valid URL pointing to the uploaded document. example: https://storage.example.com/docs/aadhaar.jpg BGVReferenceContact: type: object description: A single referee. required: - name - email properties: name: type: string description: Referee full name. example: Kavita Nair email: type: string format: email description: Referee email — the feedback mail target. example: kavita.nair@infosys.com phone: type: string description: Optional referee phone (10-digit or E.164). example: '+919111222333' designation: type: string description: Optional referee role / title. example: Team Lead whatsapp_number: type: string description: Optional referee WhatsApp number. example: '+919111222333' country_code: type: string description: Dial code (digits only). Defaults to `91`. default: '91' example: '91' securitySchemes: bearerAuth: type: http scheme: bearer description: >- API key issued by KonnectNXT. Pass as `Authorization: Bearer `. ````