Create BGV Order

This endpoint creates a new BGV (Background Verification) order.

Endpoint

POST /api.ezyhire.com/test/createBGVOrder

Headers

Header	Type	Required	Description
`USER-Key`	`string`	Yes	Your API authentication key

Request Body

Payload :
{
  "email": "string",
  "externalId": "string",
  "firstName": "string",
  "lastName": "string"
}

Request Parameters

Parameter	Type	Required	Description
`email`	`string`	Yes	Candidate’s email address
`externalId`	`string`	No	External reference ID
`firstName`	`string`	Yes	Candidate’s first name
`lastName`	`string`	Yes	Candidate’s last name

Responses

Success Response

Status Code: 200 OK

{
  "statusCode": 200,
  "error": null,
  "message": "BGV Order created.",
  "data": {
    "bgvOrderId": "c85769fd-2975-4b0f-a35c-6594983751dc",
    "externalId": "EXT123456",
    "firstName": "John",
    "lastName": "Doe",
    "email": "johndoe@gmail.com",
    "dateOfBirth": null,
    "consent": null,
    "consentTimestamp": null,
    "orderType": "STANDARD_CHECK",
    "orderStatus": "IN_PROGRESS",
    "createdOn": [2025, 8, 13, 11, 34, 11, 785825500],
    "updatedOn": [2025, 8, 13, 11, 34, 11, 785825500],
    "bgvUrl": "https://app.ezyhire.com//bgv/candidate/register/c85769fd-2975-4b0f-a35c-6594983751dc",
    "subOrderDetails": null
  }
}

After the order is placed, you must redirect the user to the URL provided in the bgvUrl field in the response. This URL allows the user to complete their Background Verification process.

Error Responses

Unauthorized

Status Code: 401 Unauthorized

{
  "status": 401,
  "message": "Invalid User/API key",
  "data": "Please provide a valid User/API key"
}

Internal Server Error

Status Code: 500 Internal Server Error

{
  "statusCode": 500,
  "error": "string",
  "message": "string",
  "data": "string"
}

License Error Responses

Status Code: 401 Unauthorized

Status Code: 401 Unauthorized 
Content:json
{
"status": 401,
"message": "Licence exhausted for Background Verification Service.",
"data": "Please purchase a new licence."
}

Status Code: 401 Unauthorized 
Content:json
{
"status": 401,
"message": "You dont have licence to use the Background Verification Service.",
"data": "Please acquire the necessary product key."
}

Example Usage

const response = await fetch('https://api.ezyhire.com/test/createBGVOrder', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'USER-Key': 'your-api-key-here'
  },
  body: JSON.stringify({
    "email": "string",
    "externalId": "string",
    "firstName": "string",
    "lastName": "string"}
  })
});
 
const data = await response.json();

Track Licenses Usage Get BGV Order By Order ID