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"
}
}
Skill Verification
Init Session
Initialize a skill verification session for a student.
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.array
required
array
required
array
Optional array of skill IDs to verify against.
Response
boolean
true on success.object
Show Response fields
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) orphoneNumber. Creates a new user if not found. - Session storage: Stored in Redis with a 40-day TTL. A reverse lookup key
verification:{recordVerificationId}→sessionTokenis also stored. - Callback registration: A
VerificationCallbackrecord is upserted usingrecordVerificationIdas the unique key. - Mode: Derived from the API key —
liveortest. 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"
}
}