Skip to main content
POST

Authorizations

X-API-Key
string
header
required

Your institute's API key, vak_eval_ followed by 48 hex characters. An institute admin creates keys in the dashboard under Settings -> Integrations -> API keys.

Headers

Idempotency-Key
string

Optional. Any unique string of 1-255 printable ASCII characters (a UUID works). Retrying with the same key within 48 hours replays the first response with Idempotent-Replayed: true.

Maximum string length: 255
Example:

"exam-cbse-sci-10a-2026-10-14"

Path Parameters

examId
string<uuid>
required

Exam id (UUID).

Body

application/json
candidate
object

Inline candidate (created or updated by external_id). Send this or candidate_id.

candidate_id
string

Evalezy candidate id. Send this or candidate.

upload_id
string

Handwritten exams: the id of a ready upload.

replace
boolean

Replace the candidate's existing live submission (not allowed once finalized).

metadata
object

A JSON object of your own, up to 2 KB, returned on the submission.

images
string[]

Not available yet (422 feature_not_available).

files
string[]

Not available yet (422 feature_not_available).

answers
object[]

Typed exams: one entry per answered question.

Response

Accepted: evaluation queued.

Status of one submission. Create, get, lists and the feed all return this shape.

id
string<uuid>
exam_id
string<uuid>
candidate
object
state
string

live for the current submission; replaced or deleted otherwise.

Example:

"live"

replaced_by
string<uuid>

Present when this submission was replaced.

status
enum<string>
Available options:
queued,
processing,
reading,
grading,
graded,
partially_graded,
failed,
cancelled
lane
string

copy (handwritten) or typed.

pages
integer | null

Page count of the handwritten copy.

needs_review
boolean
review_reasons
string[]

Submission-level reasons, e.g. pages_beyond_vision_limit.

finalized
boolean
finalized_at
string<date-time> | null
progress
object | null
queue
object | null

Only while queued.

attempt_count
integer

How many evaluation runs this submission has had.

rubric_version
integer | null
credits_charged
number | null

Charged credits once graded; 0 for a typed submission with only objective answers; null while running or when failed/cancelled.

error
object | null

Only when failed, e.g. copy_unreadable or language_not_supported.

metadata
object | null
created_at
string<date-time>
updated_at
string<date-time>
quote
object

The fixed price of this evaluation, known before grading.

warnings
object[]