Skip to main content
POST
/
assessment
/
submit
curl -X POST https://api.yourservice.com/api/v1/assessment/submit \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "answers": [
      { "questionId": "uuid-q-1", "selectedAnswer": 1 },
      { "questionId": "uuid-q-2", "selectedAnswer": 0 }
    ]
  }'

{
  "success": true,
  "data": {
    "recordVerificationId": "ver_live_abc123",
    "result": {
      "score": 80,
      "passed": true,
      "attemptNumber": 1,
      "correctAnswers": 8,
      "totalQuestions": 10,
      "message": "You have successfully passed the assessment and earned the Verified skill."
    },
    "verifiedSkills": [
      {
        "skillId": "skill_001",
        "name": "React",
        "verified": true,
        "status": "verified",
        "verifiedAt": "2025-04-09T10:05:00.000Z",
        "verifiedBy": "assessment"
      }
    ],
    "skillsUpdated": 1,
    "webhook": { "sent": true }
  },
  "message": "Assessment submitted successfully"
}

​
Overview

All answers must be submitted in a single call. The number of answers must exactly match the number of questions generated.
  • Skills are set to verified if the student passes.
  • Skills are set to rejected if the student fails.
  • A verification.completed webhook is fired with full results.
  • A result email is sent to the student.
  • A passed assessment is locked — isLocked: true — blocking all future attempts.
Requires a valid session token via the x-api-key session middleware.

​
Scoring Rules

MetricDetail
Pass threshold60%
Score formularound((correctAnswers / totalQuestions) × 100)
Lock on passisLocked: true — blocks all future attempts

​
Request Body

​
answers
array
required
Array of answer objects. Length must match the total number of questions.

​
Error Codes

CodeHTTPDescription
MISSING_VERIFICATION_ID400No recordVerificationId in session
MISSING_ANSWERS400answers is missing or empty
NO_QUESTIONS404No questions found — generate must be called first
INCOMPLETE_ANSWERS400Number of answers does not match total questions
INTERNAL_ERROR500Unexpected server error
curl -X POST https://api.yourservice.com/api/v1/assessment/submit \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "answers": [
      { "questionId": "uuid-q-1", "selectedAnswer": 1 },
      { "questionId": "uuid-q-2", "selectedAnswer": 0 }
    ]
  }'

{
  "success": true,
  "data": {
    "recordVerificationId": "ver_live_abc123",
    "result": {
      "score": 80,
      "passed": true,
      "attemptNumber": 1,
      "correctAnswers": 8,
      "totalQuestions": 10,
      "message": "You have successfully passed the assessment and earned the Verified skill."
    },
    "verifiedSkills": [
      {
        "skillId": "skill_001",
        "name": "React",
        "verified": true,
        "status": "verified",
        "verifiedAt": "2025-04-09T10:05:00.000Z",
        "verifiedBy": "assessment"
      }
    ],
    "skillsUpdated": 1,
    "webhook": { "sent": true }
  },
  "message": "Assessment submitted successfully"
}