Skip to main content
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"]
  }'

{
  "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"
}

​
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

​
studentId
string
required
External student identifier from your system.
​
callbackWebhookUrl
string
required
URL to receive verification.initiated and verification.completed webhook callbacks.
​
name
string
required
Full name of the student.
​
email
string
Student email address. Required if phoneNumber is absent.
​
phoneNumber
string
Student phone number. Required if email is absent.
​
projects
array
required
List of student project objects. Can be empty only if experience or certificates is non-empty.
​
experience
array
required
List of student work experience objects.
​
certificates
array
required
List of student certificate objects.
​
skillIds
array
Optional array of skill IDs to verify against.

​
Response

​
success
boolean
true on success.
​
data
object
​
executionTime
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

RuleError Code
studentId missingMISSING_STUDENT_ID
callbackWebhookUrl missingMISSING_CALLBACK_WEBHOOK_URL
name missingMISSING_NAME
Both email and phoneNumber missingMISSING_CONTACT
projects, experience, or certificates not an arrayINVALID_DATA_FORMAT
All three arrays are emptyNO_DATA
skillIds provided but not an arrayINVALID_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"]
  }'

{
  "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"
}