Trigger BGV Process | Gradii API Documentation

curl -X POST https://gradii.ai/api/v2/bgv/trigger \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "campaignId": "123e4567-e89b-12d3-a456-426614174000",
  "candidateName": "John Doe",
  "candidateEmail": "john.doe@example.com",
  "candidatePhone": "+1234567890",
  "priority": "medium",
  "requestTypes": [
    "identity",
    "employment",
    "education"
  ],
  "expectedCompletionDays": 7,
  "notes": "External BGV request"
}'

{
  "success": true,
  "data": {
    "bgvRequestId": "bgv_123456",
    "candidateId": "cand_789",
    "campaignId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "initiated",
    "verificationTypes": [
      "identity",
      "employment",
      "education"
    ],
    "expectedCompletionAt": "2024-01-15T12:00:00.000Z",
    "verificationPortalLink": "https://gradii.ai/bvg/portal/bgv_123456",
    "emailSent": true,
    "totalRequests": 3,
    "requests": [
      {
        "id": "req_001",
        "type": "identity",
        "priority": "medium",
        "status": "pending"
      },
      {
        "id": "req_002",
        "type": "employment",
        "priority": "medium",
        "status": "pending"
      },
      {
        "id": "req_003",
        "type": "education",
        "priority": "medium",
        "status": "pending"
      }
    ]
  },
  "message": "BGV process initiated successfully with email sent to candidate",
  "timestamp": "2024-01-28T10:00:00Z",
  "version": "2.0"
}

Initiate background verification for a candidate externally with same email template as internal BGV

Required permissions: bgv:verify.

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.

campaignIdstringRequiredformat: "uuid"

Valid campaign ID

candidateNamestringRequired

Full name of candidate (1-100 chars)

candidateEmailstringRequiredformat: "email"

Valid email address

candidatePhonestringRequired

Contact number (max 30 chars)

prioritystringOptional

low|medium|high|urgent (default: medium)

requestTypeslist of anyOptional

Verification types: identity|employment|education|criminal|reference (default: [identity,employment,education])

expectedCompletionDaysintegerOptional

1-30 days (default: 7)

notesstringOptional

Additional notes (max 500 chars)

Response

BGV process initiated successfully

successbooleanOptional

dataobjectOptional

messagestringOptional

timestampstringOptional

versionstringOptional

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

409

Conflict Error