BGV Order Status Change Webhook Payload

This webhook is triggered when a BGV (Background Verification) order’s sub-orders status changes. You can track BGV status changes through this webhook payload.

Use this webhook to receive real-time status updates for individual sub-orders within a BGV order (SSN Trace, NatCrim, Sex Offender, Global Watchlist, ID Verification, etc.).

Webhook Event

Event Type: BGV_ORDER_STATUS_CHANGE

Payload

{
  "orderId": "61571280-6597-44c2-84a6-cb813d1c30d2",
  "externalCandidateId": "EXT123456",
  "subOrders": [
    {
      "subOrderId": "f1662894-cda6-424f-bc8f-4ccecea1201e",
      "subOrderProductType": "SSN_TRACE",
      "subOrderStatus": "COMPLETED"
    },
    {
      "subOrderId": "25822562-29d2-48eb-8252-6789d6d3bb2c",
      "subOrderProductType": "NATCRIM",
      "subOrderStatus": "IN_PROGRESS"
    },
    {
      "subOrderId": "1e900661-ac37-414a-96a0-0393ce352d64",
      "subOrderProductType": "SEX_OFFENDER",
      "subOrderStatus": "PENDING"
    }
  ]
}

Payload Fields

Field	Type	Description
`orderId`	`string`	BGV order identifier
`externalCandidateId`	`string`	External candidate ID provided by client
`subOrders`	`array`	Array of sub-order status updates

Sub-Order Fields

Field	Type	Description
`subOrderId`	`string`	Unique identifier of the sub-order
`subOrderProductType`	`enum`	Type of background check product
`subOrderStatus`	`enum`	Current status of the sub-order

Product Type Values

Product Type	Description
`SSN_TRACE`	Social Security Number Trace
`NATCRIM`	National Criminal Background Check
`SEX_OFFENDER`	Sex Offender Registry Check
`GLOBAL_SECURITY_CHECK`	Global Security Check
`ID_VERIFICATION`	Identity Verification
`EDUCATION_VERIFICATION`	Education Verification
`EMPLOYMENT_VERIFICATION`	Employment Verification
`ADDRESS_VERIFICATION`	Address Verification
`CRIMINAL`	Criminal Background Check

Sub-Order Status Values

Status	Description
`PENDING`	Sub-order is pending processing
`IN_PROGRESS`	Sub-order is currently being processed
`COMPLETED`	Sub-order has been completed successfully
`NEED_INFO`	Additional information is required
`CANCELLED`	Sub-order has been cancelled
`ERROR`	Sub-order encountered an error

Example Webhook Handler

app.post('/webhook/bgv-order-status-change', (req, res) => {
  const { orderId, externalCandidateId, subOrders } = req.body;
  
  console.log('BGV Order Status Change:', {
    orderId,
    externalCandidateId,
    subOrdersCount: subOrders.length
  });
  
  // Process each sub-order status change
  subOrders.forEach(subOrder => {
    console.log(`Sub-order ${subOrder.subOrderId} (${subOrder.subOrderProductType}): ${subOrder.subOrderStatus}`);
    
    // Handle different status changes
    switch (subOrder.subOrderStatus) {
      case 'COMPLETED':
        // Handle completed sub-order
        break;
      case 'NEED_INFO':
        // Handle sub-order requiring additional information
        break;
      case 'IN_PROGRESS':
        // Handle sub-order in progress
        break;
    }
  });
  
  // Process the webhook data
  // Update your database, send notifications to relevant parties, etc.
  
  res.status(200).json({ received: true });
});

BGV Need Info Register API Webhook