Skip to main content
POST
/
verification
/
bgv
/
initiate
/
cURL
curl --request POST \
  --url https://bgv.konnectnxt.com/api/verification/bgv/initiate/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "requestFor": [
    "AADHAAR"
  ],
  "aadhaar": {
    "aadhaar_number": "*****678910"
  },
  "pan": {
    "pan_number": "*****0751P"
  },
  "employment_history": {
    "uan_number": "*****450116"
  },
  "last_employment": {
    "mobile_number": "*****13041"
  },
  "passport": {
    "file_number": "*****5796920",
    "dob": "01/01/1980",
    "employee_name": "John Doe"
  },
  "crime_check_initiate": {
    "full_name": "Jane Smith",
    "email_address": "jane.smith@example.com",
    "mobile_number": "*****47129",
    "gender": "Female",
    "address_type": "PERMANENT",
    "house_no": "*****Na",
    "colony": "North Colony",
    "pincode": "*****550",
    "city": "Mumbai",
    "state": "Maharashtra",
    "country": "India",
    "doc_type": "AADHAAR",
    "front_doc_url": "https://example.com/doc.png",
    "absence_contact_details": {
      "full_name": "Doe John",
      "relation": "Friend",
      "phone_number": "*****67890"
    }
  },
  "reference_check_initiate": {
    "reference_details": [
      {
        "name": "Alex Doe",
        "email": "alex.doe@example.com",
        "designation": "Manager",
        "contact_number": "*****49012",
        "whatsapp_number": "*****13464"
      }
    ],
    "candidate_details": {
      "name": "Mary Jane",
      "email": "mary.jane@example.com",
      "designation": "Software Engineer",
      "start_date": "01-01-2023",
      "end_date": "31-12-2023",
      "salary": 7,
      "employer_name": "TechCorp",
      "employee_id": "EMP67890"
    }
  }
}'
{
  "status": "success",
  "code": 200,
  "message": "Data Fetched Successfully>",
  "data": {
    "aadhaar": {
      "result": {
        "verified": "true",
        "ageBand": "20-30",
        "state": "Uttar Pradesh",
        "mobileNumber": "*******090",
        "gender": "MALE"
      }
    },
    "pan": {
      "name": "AMIT KUMAR",
      "number": "C03D3G7513",
      "typeOfHolder": "Individual or Person",
      "isIndividual": true,
      "isValid": true,
      "firstName": "AMIT",
      "middleName": "",
      "lastName": "KUMAR",
      "title": "",
      "panStatus": "VALID",
      "panStatusCode": "E",
      "aadhaarSeedingStatus": "Successful",
      "aadhaarSeedingStatusCode": "Y",
      "lastUpdatedOn": "",
      "individualTaxComplianceStatus": "operative"
    },
    "passport": {
      "verified": "true",
      "message": "Verification completed with positive results",
      "upstreamName": "John Doe"
    },
    "crime_check_initiate": {
      "candidate_sv_id": 29392,
      "status": "in progress",
      "email_address": "john.doe@example.com",
      "full_name": "John Doe",
      "mobile_number": "0987654321"
    },
    "reference_check_initiate": {
      "status": "in progress"
    }
  },
  "credits_used": 3,
  "credits_left": 4040
}
The BGV Initiate API is the starting point for initiating background verification checks for candidates. Whether you need to validate employment history, PAN details, or even check criminal records, this API can handle multiple types of checks in a single request.

​
How It Works

To use this API, you’ll need to provide a few essential pieces of information:
  1. Candidate Information: This includes basic details such as the name, date of birth, and type of verification you need.
  2. Verification Types: Choose which checks need to be performed—like PAN validation, employment verification, criminal checks, etc.
  3. Specific Data for Each Check: Each check may require specific information. For example:
    • PAN Verification: You need to provide the candidate’s PAN number.
    • Employment Verification: You will need the candidate’s last employer, job title, and employment dates
Make sure to include all required fields for the specific check types you are initiating. Missing data can result in errors.

​
Why Use the BGV Initiate API?

This API is powerful because it allows you to initiate multiple checks at once, saving time and reducing the complexity of having to call separate APIs for each check. You can include all the necessary details in one request, making the process streamlined and easy to manage.
Always keep a record of the Case ID you receive in the response. It’s your key to tracking the verification status. -
You can track the status of your case using BGV Status API.
If a key (e.g., AADHAAR, PAN, PASSPORT etc.) is included in the requestFor array, all fields under that key become mandatory and must be provided.

​
Error Handling in the API Response

The API is designed to report errors in a structured and intuitive way. If any error occurs during the processing of a specific check, the error details will be encapsulated within that particular section. This ensures clarity and prevents errors from affecting unrelated sections of the response.

​
1. Error Format

  • Fields:
    • error: A descriptive message about the issue.
    • status_code: The HTTP status code representing the type of error.
  • Errors are included only in the section where they occur, leaving other sections unaffected.

​
2. Example of an Error in a Section

If you give invalid information or some different issue is there then it will return some error to you for the individual entity but other components will remain intact. For Example: If aadhaar number is missing or wrong but pan details are correct then response would be something like this: 
{
  "code": 200,
  "status": "success",
  "message": "Data Fetched Successfully.",
  "data": {
    "aadhaar": {
      "error": "Aadhaar number is missing.",
      "status_code": 400
    },
    "pan": {
      "name": "<name>",
      "number": "<pan_number>",
      "typeOfHolder": "Individual or Person",
      "isIndividual": true,
      "isValid": true,
      "firstName": "<first_name>",
      "middleName": "<middle_name>",
      "lastName": "<last_name>",
      "title": "",
      "panStatus": "VALID",
      "panStatusCode": "E",
      "aadhaarSeedingStatus": "Successful",
      "aadhaarSeedingStatusCode": "Y",
      "lastUpdatedOn": ""
    }
  },
  "credits_used": 6,
  "credits_remaining": 61
}
Other sections will continue to display their respective statuses and data without disruption.
Since this API contains multiple sub-APIs, each API call may return a different error message. Example Error Response for Individual entity:

​
Aadhaar Error Codes

{
  "aadhaar": {
    "error": "<error_message>",
    "status_code": 400
  }
}
Status CodeMessage
400Aadhaar number is missing.
400Aadhaar Number '' must be 12 Digits.
400Aadhaar Number is invalid
400Aadhaar Number is not allowed to be an empty string
400Aadhaar Number must be a string
409Upstream Down
500Internal Server Error

​
PAN Error Codes

{
  "pan": {
    "error": "<error_message>",
    "status_code": 400
  }
}
Status CodeMessage
400PAN number is missing.
400PAN Number '' must be 10 Digits.
400number is required
400number is not allowed to be empty.
400number must be a string
400PAN number is not valid
404Pan Number Not Found
409Upstream Down
500Internal Server Error

​
Passport Error Codes

{
  "passport": {
    "error": "<error_message>",
    "status_code": 400
  }
}
Status CodeMessage
400file_number, dob, employee_name is missing. (If any field is missing).
404File No not Found
409Upstream Down
500Internal Server Error

​
Crime Check Error Codes

{
  "crime_check_initiate": {
    "error": "<error_message>",
    "status_code": 400
  }
}
Status CodeMessage
400Candidate Name contains special characters or numbers.
400Please enter a valid email address.
400Invalid document Url.
400Please enter the valid mobile number.
400{“message”: “Please enter only allowed gender types.”, “data”: { “allowed_address_type”: [“male”, “female”, “other”] }}
400{“message”: “Some fields are missing or empty. Please add the + fields”, “data”: { “missing_fields”: [“full_name”, “email_address”], “empty_fields”: [“gender”] }}
500Unable to add candidate for crime check at the moment. Please contact support.
500Internal Server Error

​
Reference Check Error Codes

{
  "reference_check_initiate": {
    "error": "<error_message>",
    "status_code": 400
  }
}
Status CodeMessage
400Reference/Candidate email is required.
400Reference/Candidate name is required.
400Reference/Candidate email is not valid.
400Reference/Candidate name is designation.
400Reference contact/whatsapp number is required.
400Valid reference contact/whatsapp number is required (10 digits).
400Candidate employer name is required.
400Future dates are not allowed.
400Start date cannot be more than End date.
500Unable to add candidate for reference check at the moment. Please contact support.
500Internal Server Error

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
requestFor
enum<string>[]
required
Minimum length: 1
​
aadhaar
object
​
pan
object
​
employment_history
object
​
last_employment
object
​
passport
object
​
crime_check_initiate
object
​
reference_check_initiate
object

Response

Case Created Successfully

​
status
enum<string>
required

Overall status of the API

Available options:
success,
error
​
code
integer
required

HTTP status code

​
message
string
required

Description of the response or error

​
data
object
required
​
credits_used
integer
required

Represents the total number of credits used in this request.

Example:

3

​
credits_left
integer
required

Represents the remaining credits available for use.

Example:

4040