BGV Completed Webhook | Gradii API Documentation

{
  "event": "bgv.completed",
  "timestamp": "2024-01-15T15:30:00.000Z",
  "version": "2.0",
  "companyId": "123e4567-e89b-12d3-a456-426614174000",
  "bgvRequestId": "bgv_abc123xyz",
  "candidateId": "cand_def456",
  "requestType": "identity",
  "status": "completed",
  "candidate": {
    "id": "cand_def456",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+919876543210"
  },
  "company": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Tech Corp"
  },
  "campaignId": "camp_ghi789",
  "verificationResult": "verified",
  "confidenceScore": 95,
  "completedAt": "2024-01-15T15:30:00.000Z",
  "campaign": {
    "id": "camp_ghi789",
    "jobTitle": "Software Engineer"
  },
  "digilockerData": {
    "profile": {
      "digilockerid": "1234567890123456",
      "name": "John Doe",
      "dob": "1990-01-01",
      "gender": "M",
      "eaadhaar": "XXXX-XXXX-1234",
      "mobile": "+91XXXXXXXXXX"
    },
    "address": {
      "house": "123",
      "street": "Main Street",
      "locality": "Downtown",
      "dist": "Central",
      "state": "Maharashtra",
      "pincode": "400001"
    },
    "hasPicture": true,
    "apaar": {
      "apaar_id": "APAAR123456789"
    },
    "dataCompleteness": 90,
    "scopesGranted": [
      "openid",
      "profile",
      "address",
      "picture",
      "aadhaar"
    ],
    "consentTimestamp": "2024-01-15T10:00:00.000Z",
    "lastDataSync": "2024-01-15T15:28:00.000Z",
    "documentsVerified": 2,
    "documents": [
      {
        "id": "doc_001",
        "type": "PANCR",
        "name": "PAN Card",
        "status": "verified",
        "verificationResult": "verified",
        "hmacVerified": true,
        "fileSize": 45678,
        "mimeType": "application/pdf",
        "processedAt": "2024-01-15T15:25:00.000Z"
      },
      {
        "id": "doc_002",
        "type": "ADHAR",
        "name": "Aadhaar Card",
        "status": "verified",
        "verificationResult": "verified",
        "hmacVerified": true,
        "fileSize": 38921,
        "mimeType": "application/pdf",
        "processedAt": "2024-01-15T15:26:00.000Z"
      }
    ]
  }
}

Webhook payload delivered to your registered URL when a BGV verification event fires. Subscribe to ‘bgv.completed’, ‘bgv.initiated’, ‘bgv.in_progress’, ‘bgv.failed’, ‘bgv.updated’, or ‘bgv.cancelled’ in your webhook configuration. The bgv.completed event includes full DigiLocker verification data.

Payload

The payload of this webhook request is an object.

eventstringRequired

timestampdatetimeRequired

When the event occurred

versionstringRequired

API version (e.g., ‘2.0’)

companyIdstringRequiredformat: "uuid"

Your company ID

bgvRequestIdstringRequiredformat: "uuid"

BGV verification request ID

candidateIdstringRequiredformat: "uuid"

Candidate ID

requestTypestringRequired

Verification type: identity | employment | education | criminal | reference

statusstringRequired

BGV status: pending | in_progress | completed | failed | cancelled

candidatemap from strings to anyRequired

Candidate profile info (id, name, email, phone)

companymap from strings to anyRequired

Company info (id, name)

campaignIdstringOptionalformat: "uuid"

Job campaign ID

verificationResultstringOptional

Result: verified | unverified | inconclusive (null until completed)

confidenceScoredoubleOptional

Confidence score 0-100 (null until completed)

completedAtdatetimeOptional

When verification completed (null if not yet complete)

campaignmap from strings to anyOptional

Job campaign info (id, jobTitle)

digilockerDatamap from strings to anyOptional

Full DigiLocker data (only on bgv.completed): profile, address, documents, APAAR, dataCompleteness, scopesGranted

Response

200

Your webhook endpoint should return 200 OK to acknowledge receipt