eProctor Gateway API

curl https://gateway.eproctor.app/api/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "epc_live_...",
    "client_secret": "eps_live_...",
    "scope": "organization.read exams.read sessions.read results.read"
  }'

{
  "access_token": "epat_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "organization.read exams.read sessions.read results.read"
}

{
  "data": {
    "status": "available",
    "apiVersion": "v1",
    "resources": [
      "organization",
      "deletionImpact",
      "options",
      "centers",
      "exams",
      "assessments",
      "sessions",
      "sessionCandidatesAndCredentials",
      "finalizeAndResults"
    ]
  }
}

curl -X POST https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/cleanup \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d 'GET /api/v1/organizations/{organizationId}/delete-impact?module=session&recordId=sess_32f8&examId=exam_01hzy&assessmentId=asmt_8ds21&sessionId=sess_32f8'

{
  "ok": true,
  "impact": {
    "module": "session",
    "recordId": "sess_32f8",
    "recommendedAction": "archive",
    "canHardDelete": false,
    "canArchive": true,
    "blockers": [],
    "warnings": [
      {
        "key": "credentials_disabled",
        "label": "Candidate credentials exist. They will be disabled with the archived session.",
        "count": 120
      }
    ]
  }
}

{
  "ok": true,
  "queued": true,
  "impact": {
    "scopeType": "exam",
    "recordId": "exam_01hzy"
  },
  "job": {
    "id": "cleanup_job_01",
    "status": "queued",
    "progressPercent": 0
  }
}

{
  "object": "organization",
  "id": "org_7c7b1a",
  "name": "Publish Jobs",
  "status": "active",
  "subscription_status": "active",
  "created_at": "2026-06-16T09:00:00.000Z"
}

curl -X POST https://gateway.eproctor.app/api/v1/organizations/{organizationId}/proctoring-centers \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "title": "Islamabad Center",
  "description": "Main testing lab for Islamabad candidates",
  "status": "active"
}'

{
  "object": "proctoring_center",
  "id": "center_9b1f23",
  "title": "Islamabad Center",
  "description": "Main testing lab for Islamabad candidates",
  "status": "active",
  "created_at": "2026-06-16T09:15:00.000Z"
}

curl -X PUT https://gateway.eproctor.app/api/v1/organizations/{organizationId}/proctoring-centers/{centerId} \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "title": "Islamabad Center - Lab A",
  "description": "Updated center description",
  "status": "active"
}'

{
  "data": {
    "id": "center_9b1f23",
    "title": "Islamabad Center - Lab A",
    "description": "Updated center description",
    "status": "active",
    "updated_at": "2026-06-16T10:15:00.000Z"
  }
}

{
  "object": "list",
  "data": [
    { "id": "atype_cbt", "key": "cbt", "title": "Computer Based Test" },
    { "id": "atype_mcq_single", "key": "mcq_single", "title": "MCQ Single Correct" }
  ],
  "has_more": false
}

curl -X POST https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "name": "Mock Exam",
  "description": "Optional description",
  "status": "active"
}'

{
  "object": "exam",
  "id": "exam_01hzy",
  "name": "Mock Exam",
  "description": "Optional description",
  "status": "active",
  "created_at": "2026-06-16T09:20:00.000Z"
}

curl -X PUT https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId} \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "name": "Exam By Postman",
  "description": "Optional description Update By Postman",
  "status": "active"
}'

{
  "data": {
    "id": "exam_01hzy",
    "name": "Exam By Postman",
    "description": "Optional description Update By Postman",
    "status": "active",
    "updated_at": "2026-06-16T10:20:00.000Z"
  }
}

curl -X POST https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/assessments \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "name": "Mock Assessment",
  "description": "Optional description",
  "assessment_type_option_id": "atype_cbt",
  "status": "active"
}'

{
  "object": "assessment",
  "id": "asmt_8ds21",
  "exam_id": "exam_01hzy",
  "name": "Mock Assessment",
  "assessment_type_option_id": "atype_cbt",
  "status": "active"
}

curl -X PUT https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/assessments/{assessmentId} \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "name": "Updated Mock Assessment",
  "description": "Updated assessment description",
  "assessment_type_option_id": "atype_cbt",
  "status": "active"
}'

{
  "data": {
    "id": "asmt_8ds21",
    "exam_id": "exam_01hzy",
    "name": "Updated Mock Assessment",
    "status": "active",
    "updated_at": "2026-06-16T10:25:00.000Z"
  }
}

curl -X POST https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/candidate-lists \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "name": "Mock Candidate List",
  "description": "Candidates imported from admission system",
  "status": "active"
}'

{
  "object": "candidate_list",
  "id": "clist_4f91",
  "exam_id": "exam_01hzy",
  "name": "Mock Candidate List",
  "status": "active",
  "candidate_count": 0
}

curl -X PUT https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/candidate-lists/{listId} \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "name": "Updated Candidate List",
  "description": "Updated list notes",
  "status": "active"
}'

{
  "data": {
    "id": "clist_4f91",
    "exam_id": "exam_01hzy",
    "name": "Updated Candidate List",
    "status": "active",
    "candidate_count": 0
  }
}

curl -X POST https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/candidate-lists/{listId}/members \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "mode": "upsert",
  "source": "publish_jobs",
  "candidates": [
    {
      "name": "Candidate One",
      "email": "candidate@example.com",
      "external_candidate_id": "pj_user_123",
      "meta": {
        "source": "publish_jobs",
        "pj_business_id": "business_id",
        "pj_job_id": "job_id",
        "pj_stage_id": "stage_id",
        "pj_user_draggable_id": "pivot_id"
      }
    }
  ]
}'

{
  "object": "bulk_candidate_list_member_import",
  "inserted": 450,
  "updated": 45,
  "skipped": 5,
  "failed": 0,
  "errors": [],
  "data": [
    {
      "id": "cand_70ae",
      "external_candidate_id": "pj_user_123",
      "email": "candidate@example.com",
      "status": "active"
    }
  ]
}

curl -X PUT https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/candidate-lists/{listId}/members/{memberId} \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "name": "Candidate One Updated",
  "email": "candidate@example.com",
  "external_candidate_id": "pj_user_123",
  "meta": {
    "source": "publish_jobs",
    "pj_job_id": "job_id",
    "pj_stage_id": "stage_id",
    "campus": "Islamabad"
  }
}'

{
  "data": {
    "id": "cand_70ae",
    "name": "Candidate One Updated",
    "email": "candidate@example.com",
    "external_candidate_id": "pj_user_123",
    "status": "active"
  }
}

curl -X POST https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/candidate-lists/{listId}/groups \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "name": "Batch A",
  "description": "Morning candidates",
  "member_ids": ["cand_70ae"]
}'

{
  "object": "candidate_group",
  "id": "cgrp_2ca4",
  "candidate_list_id": "clist_4f91",
  "name": "Batch A",
  "member_count": 1
}

curl -X PUT https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/candidate-lists/{listId}/groups/{groupId} \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "name": "Batch A Updated",
  "description": "Updated morning candidates"
}'

{
  "data": {
    "id": "cgrp_2ca4",
    "candidate_list_id": "clist_4f91",
    "name": "Batch A Updated",
    "member_count": 1
  }
}

curl -X POST https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/assessments/{assessmentId}/schedule \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "title": "Morning Schedule",
  "start_at": "2026-06-16T09:00:00+05:00",
  "end_at": "2026-06-16T12:00:00+05:00",
  "duration_minutes": 180,
  "buffer_minutes": 0,
  "capacity_per_slot": 100,
  "status": "active"
}'

{
  "object": "assessment_schedule",
  "id": "sch_803b",
  "assessment_id": "asmt_8ds21",
  "title": "Morning Schedule",
  "start_at": "2026-06-16T09:00:00+05:00",
  "end_at": "2026-06-16T12:00:00+05:00",
  "duration_minutes": 180,
  "status": "active"
}

curl -X PUT https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/assessments/{assessmentId}/schedule/{scheduleId} \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "title": "Morning Schedule Updated",
  "start_at": "2026-06-16T09:30:00+05:00",
  "end_at": "2026-06-16T12:30:00+05:00",
  "duration_minutes": 180,
  "buffer_minutes": 10,
  "capacity_per_slot": 100,
  "status": "active"
}'

{
  "data": {
    "id": "sch_803b",
    "title": "Morning Schedule Updated",
    "start_at": "2026-06-16T09:30:00+05:00",
    "end_at": "2026-06-16T12:30:00+05:00",
    "duration_minutes": 180,
    "status": "active"
  }
}

curl -X PUT https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/assessments/{assessmentId}/settings \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "settings": [
    { "key": "show_immediate_result", "enabled": true, "value": "true" },
    { "key": "delivery_mode", "enabled": true, "value": "online" },
    { "key": "webcam_required", "enabled": true, "value": "true" },
    { "key": "fullscreen_lock", "enabled": true, "value": "true" }
  ]
}'

{
  "object": "assessment_settings",
  "assessment_id": "asmt_8ds21",
  "settings": [
    { "key": "show_immediate_result", "enabled": true, "value": "true" },
    { "key": "delivery_mode", "enabled": true, "value": "online" },
    { "key": "webcam_required", "enabled": true, "value": "true" }
  ]
}

curl -X PUT https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/assessments/{assessmentId}/grading \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "pass_marks_enabled": true,
  "pass_marks": 50,
  "bands": [
    { "grade": "A+", "grade_label": "A+", "min_percentage": 90, "max_percentage": 100, "sort_order": 1 },
    { "grade": "A", "grade_label": "A", "min_percentage": 80, "max_percentage": 89.99, "sort_order": 2 },
    { "grade": "F", "grade_label": "F", "min_percentage": 0, "max_percentage": 49.99, "sort_order": 6 }
  ]
}'

{
  "object": "assessment_grading",
  "assessment_id": "asmt_8ds21",
  "pass_marks_enabled": true,
  "pass_marks": 50,
  "bands": [
    { "grade": "A+", "min_percentage": 90, "max_percentage": 100 },
    { "grade": "A", "min_percentage": 80, "max_percentage": 89.99 },
    { "grade": "F", "min_percentage": 0, "max_percentage": 49.99 }
  ]
}

{
  "object": "session_options",
  "schedules": [
    { "id": "sch_803b", "title": "Morning Schedule", "status": "active" }
  ],
  "papers": [
    { "id": "paper_24d2", "title": "English Mock Paper" }
  ],
  "paper_variants": [
    { "id": "variant_a", "paper_id": "paper_24d2", "label": "A", "status": "locked" }
  ],
  "proctoring_centers": [
    { "id": "center_9b1f23", "title": "Islamabad Center" }
  ],
  "candidate_lists": [
    { "id": "clist_4f91", "name": "Mock Candidate List", "candidate_count": 120 }
  ],
  "candidate_list_groups": [
    { "id": "cgrp_2ca4", "candidate_list_id": "clist_4f91", "name": "Batch A" }
  ],
  "settings_summary": {
    "delivery_mode": "online",
    "webcam_required": true,
    "fullscreen_lock": true
  },
  "grading_summary": {
    "pass_marks_enabled": true,
    "pass_marks": 50
  }
}

curl -X POST https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/assessments/{assessmentId}/sessions \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "title": "Morning Session",
  "status": "active",
  "schedule_id": "sch_803b",
  "paper_id": "paper_24d2",
  "paper_resolution_id": "variant_a",
  "proctoring_center_ids": ["center_9b1f23"],
  "target_mode": "list",
  "candidate_list_id": "clist_4f91",
  "candidate_list_group_id": null
}'

{
  "object": "assessment_session",
  "id": "sess_32f8",
  "assessment_id": "asmt_8ds21",
  "title": "Morning Session",
  "status": "active",
  "schedule_id": "sch_803b",
  "paper_id": "paper_24d2",
  "paper_resolution_id": "variant_a",
  "target_mode": "list",
  "candidate_list_id": "clist_4f91",
  "candidate_count": 120,
  "created_at": "2026-06-16T10:00:00.000Z"
}

curl -X PUT https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/assessments/{assessmentId}/sessions/{sessionId} \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "title": "Morning Session Updated",
  "status": "active"
}'

{
  "data": {
    "id": "sess_32f8",
    "title": "Morning Session Updated",
    "status": "active",
    "updated_at": "2026-06-16T10:30:00.000Z"
  }
}

curl -X POST https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/assessments/{assessmentId}/sessions/{sessionId}/candidates/bulk \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "candidates": [
    {
      "name": "Candidate One",
      "email": "candidate@example.com",
      "external_candidate_id": "EXT-001",
      "meta": { "rollNo": "101" }
    },
    {
      "name": "Candidate Two",
      "email": "candidate2@example.com",
      "external_candidate_id": "EXT-002",
      "meta": { "rollNo": "102" }
    }
  ]
}'

{
  "object": "bulk_candidate_import",
  "inserted": 2,
  "updated": 0,
  "skipped": 0,
  "duplicates": [],
  "data": [
    { "id": "cand_70ae", "external_candidate_id": "EXT-001", "email": "candidate@example.com" },
    { "id": "cand_89bd", "external_candidate_id": "EXT-002", "email": "candidate2@example.com" }
  ]
}

curl -X POST https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/assessments/{assessmentId}/sessions/{sessionId}/credentials/bulk \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "async": true,
  "identifier_mode": "email",
  "password_mode": "random",
  "password_length": 10,
  "delivery": { "returnInResponse": false }
}'

{
  "object": "credential_generation_job",
  "id": "job_cred_11af",
  "session_id": "sess_32f8",
  "status": "queued",
  "target_mode": "list",
  "candidate_count": 120,
  "created_at": "2026-06-16T10:10:00.000Z"
}

curl -X POST https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams/{examId}/assessments/{assessmentId}/sessions/{sessionId}/close-and-generate \
  -H 'Authorization: Bearer epat_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: request-2026-001' \
  -d '{
  "reason": "All candidate attempts completed",
  "notify_webhooks": true
}'

{
  "object": "session_finalization",
  "session_id": "sess_32f8",
  "status": "closed",
  "results_status": "generated",
  "reports_status": "available",
  "completed_at": "2026-06-16T13:10:00.000Z"
}

EProctor-Delivery-Id: delivery_uuid
EProctor-Event-Type: result.generated
EProctor-Signature: t=...,v1=...
EProctor-Webhook-Version: 2026-06-11

{
  "id": "evt_91af",
  "type": "result.generated",
  "created_at": "2026-06-16T13:11:00.000Z",
  "data": {
    "organization_id": "org_7c7b1a",
    "exam_id": "exam_01hzy",
    "assessment_id": "asmt_8ds21",
    "session_id": "sess_32f8"
  }
}

curl https://gateway.eproctor.app/api/v1/organizations/{organizationId}/exams?limit=100&offset=0 \
  -H 'Authorization: Bearer epat_...'

{
  "object": "list",
  "data": [
    { "object": "exam", "id": "exam_01hzy", "name": "Mock Exam" }
  ],
  "limit": 100,
  "offset": 0,
  "has_more": false
}

Idempotency-Key: pj-job-123-stage-eproctor-batch-001

{
  "error": {
    "code": "idempotency_conflict",
    "message": "This idempotency key was already used with a different request payload.",
    "requestId": "req_..."
  }
}