Init Session

curl -X POST https://api.yourservice.com/api/v1/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "studentId": "student_123",
    "callbackWebhookUrl": "https://yourapp.com/webhooks/verification",
    "name": "Arun Kumar",
    "email": "arun@example.com",
    "projects": [
      {
        "projectId": "proj_001",
        "name": "E-Commerce App",
        "description": "Built with React and Node.js",
        "startDate": "2023-01-01"
      }
    ],
    "experience": [
      {
        "workExperienceId": "exp_001",
        "role": "Frontend Developer",
        "companyName": "TechCorp",
        "startDate": "2022-06-01",
        "endDate": "2023-01-01"
      }
    ],
    "certificates": [],
    "skillIds": ["skill_001", "skill_002"]
  }'

const response = await fetch('https://api.yourservice.com/api/v1/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your_api_key_here'
  },
  body: JSON.stringify({
    studentId: 'student_123',
    callbackWebhookUrl: 'https://yourapp.com/webhooks/verification',
    name: 'Arun Kumar',
    email: 'arun@example.com',
    projects: [{ projectId: 'proj_001', name: 'E-Commerce App' }],
    experience: [{ workExperienceId: 'exp_001', role: 'Frontend Developer', companyName: 'TechCorp' }],
    certificates: [],
    skillIds: ['skill_001', 'skill_002']
  })
});
const data = await response.json();

{
  "success": true,
  "data": {
    "sessionToken": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "recordVerificationId": "ver_live_abc123",
    "keyId": "key_xxxx",
    "recordUserId": "usr_live_xyz789",
    "externalStudentId": "student_123",
    "expiresIn": 3456000,
    "expiresAt": "2025-05-19T10:00:00.000Z"
  },
  "executionTime": "42ms"
}

{
  "success": false,
  "error": {
    "code": "MISSING_STUDENT_ID",
    "message": "Student ID is required"
  }
}

{
  "success": false,
  "error": {
    "code": "SESSION_STORAGE_FAILED",
    "message": "Failed to create session"
  }
}

POST

verify

curl -X POST https://api.yourservice.com/api/v1/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "studentId": "student_123",
    "callbackWebhookUrl": "https://yourapp.com/webhooks/verification",
    "name": "Arun Kumar",
    "email": "arun@example.com",
    "projects": [
      {
        "projectId": "proj_001",
        "name": "E-Commerce App",
        "description": "Built with React and Node.js",
        "startDate": "2023-01-01"
      }
    ],
    "experience": [
      {
        "workExperienceId": "exp_001",
        "role": "Frontend Developer",
        "companyName": "TechCorp",
        "startDate": "2022-06-01",
        "endDate": "2023-01-01"
      }
    ],
    "certificates": [],
    "skillIds": ["skill_001", "skill_002"]
  }'

const response = await fetch('https://api.yourservice.com/api/v1/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your_api_key_here'
  },
  body: JSON.stringify({
    studentId: 'student_123',
    callbackWebhookUrl: 'https://yourapp.com/webhooks/verification',
    name: 'Arun Kumar',
    email: 'arun@example.com',
    projects: [{ projectId: 'proj_001', name: 'E-Commerce App' }],
    experience: [{ workExperienceId: 'exp_001', role: 'Frontend Developer', companyName: 'TechCorp' }],
    certificates: [],
    skillIds: ['skill_001', 'skill_002']
  })
});
const data = await response.json();

{
  "success": true,
  "data": {
    "sessionToken": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "recordVerificationId": "ver_live_abc123",
    "keyId": "key_xxxx",
    "recordUserId": "usr_live_xyz789",
    "externalStudentId": "student_123",
    "expiresIn": 3456000,
    "expiresAt": "2025-05-19T10:00:00.000Z"
  },
  "executionTime": "42ms"
}

{
  "success": false,
  "error": {
    "code": "MISSING_STUDENT_ID",
    "message": "Student ID is required"
  }
}

{
  "success": false,
  "error": {
    "code": "SESSION_STORAGE_FAILED",
    "message": "Failed to create session"
  }
}

Overview

Validates the student’s data, creates or retrieves a user record, stores a session in Redis, registers a callback webhook, and returns a session token to drive the rest of the verification flow.

At least one of projects, experience, or certificates must be non-empty.

Request Body

string

required

External student identifier from your system.

string

required

URL to receive verification.initiated and verification.completed webhook callbacks.

string

required

Full name of the student.

string

Student email address. Required if phoneNumber is absent.

string

Student phone number. Required if email is absent.

array

required

List of student project objects. Can be empty only if experience or certificates is non-empty.

Show Project object fields

string

required

Your system’s unique project identifier.

string

required

Project name.

string

Project description.

string

Start date (ISO 8601).

string

End date (ISO 8601). Omit if ongoing.

array

required

List of student work experience objects.

Show Experience object fields

string

required

Your system’s unique experience identifier.

string

required

Job title or role.

string

required

Employer name.

string

Role description.

string

Start date (ISO 8601).

string

End date (ISO 8601). Omit if current role.

array

required

List of student certificate objects.

Show Certificate object fields

string

required

Your system’s unique certificate identifier.

string

required

Certificate name.

string

Issuing organisation name.

string

Issue date (ISO 8601).

array

Optional array of skill IDs to verify against.

Response

boolean

true on success.

object

Show Response fields

string

UUID used to authenticate subsequent verification steps. Store this securely.

string

Unique ID for this verification record (e.g. ver_live_xxxx).

string

The API key ID used for this request.

string

Internal user ID — created if new, or existing if matched by email/phone.

string

The studentId you passed in.

number

Session TTL in seconds. Default: 3456000 (40 days).

string

ISO 8601 timestamp of session expiry.

string

Server-side execution time (e.g. "42ms").

Behavior Notes

User lookup: Searches for an existing user by email (preferred) or phoneNumber. Creates a new user if not found.
Session storage: Stored in Redis with a 40-day TTL. A reverse lookup key verification:{recordVerificationId} → sessionToken is also stored.
Callback registration: A VerificationCallback record is upserted using recordVerificationId as the unique key.
Mode: Derived from the API key — live or test. Determines database models and ID prefixes.

Validation Rules

Rule	Error Code
`studentId` missing	`MISSING_STUDENT_ID`
`callbackWebhookUrl` missing	`MISSING_CALLBACK_WEBHOOK_URL`
`name` missing	`MISSING_NAME`
Both `email` and `phoneNumber` missing	`MISSING_CONTACT`
`projects`, `experience`, or `certificates` not an array	`INVALID_DATA_FORMAT`
All three arrays are empty	`NO_DATA`
`skillIds` provided but not an array	`INVALID_SKILL_IDS`

curl -X POST https://api.yourservice.com/api/v1/verify \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "studentId": "student_123",
    "callbackWebhookUrl": "https://yourapp.com/webhooks/verification",
    "name": "Arun Kumar",
    "email": "arun@example.com",
    "projects": [
      {
        "projectId": "proj_001",
        "name": "E-Commerce App",
        "description": "Built with React and Node.js",
        "startDate": "2023-01-01"
      }
    ],
    "experience": [
      {
        "workExperienceId": "exp_001",
        "role": "Frontend Developer",
        "companyName": "TechCorp",
        "startDate": "2022-06-01",
        "endDate": "2023-01-01"
      }
    ],
    "certificates": [],
    "skillIds": ["skill_001", "skill_002"]
  }'

const response = await fetch('https://api.yourservice.com/api/v1/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your_api_key_here'
  },
  body: JSON.stringify({
    studentId: 'student_123',
    callbackWebhookUrl: 'https://yourapp.com/webhooks/verification',
    name: 'Arun Kumar',
    email: 'arun@example.com',
    projects: [{ projectId: 'proj_001', name: 'E-Commerce App' }],
    experience: [{ workExperienceId: 'exp_001', role: 'Frontend Developer', companyName: 'TechCorp' }],
    certificates: [],
    skillIds: ['skill_001', 'skill_002']
  })
});
const data = await response.json();

{
  "success": true,
  "data": {
    "sessionToken": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "recordVerificationId": "ver_live_abc123",
    "keyId": "key_xxxx",
    "recordUserId": "usr_live_xyz789",
    "externalStudentId": "student_123",
    "expiresIn": 3456000,
    "expiresAt": "2025-05-19T10:00:00.000Z"
  },
  "executionTime": "42ms"
}

{
  "success": false,
  "error": {
    "code": "MISSING_STUDENT_ID",
    "message": "Student ID is required"
  }
}

{
  "success": false,
  "error": {
    "code": "SESSION_STORAGE_FAILED",
    "message": "Failed to create session"
  }
}

Overview

Skills

Selected Skills

Admin

Skill Verification

Step 1 — Skills

Step 2 — Verification Method

Step 3 — Source Items

Reviewer Details

Human Verification

Assessment Verification

Metadata

Overview

Request Body

Response

Behavior Notes

Validation Rules

​Overview

​Request Body

​Response

​Behavior Notes

​Validation Rules

Overview

Request Body

Response

Behavior Notes

Validation Rules