Unfinalize a submission
curl --request POST \
--url https://api.evalezy.com/v1/submissions/{submissionId}/unfinalize \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"reason": "Revaluation request RV-2026-0193"
}
'import requests
url = "https://api.evalezy.com/v1/submissions/{submissionId}/unfinalize"
payload = { "reason": "Revaluation request RV-2026-0193" }
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({reason: 'Revaluation request RV-2026-0193'})
};
fetch('https://api.evalezy.com/v1/submissions/{submissionId}/unfinalize', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"exam_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"candidate": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"external_id": "<string>"
},
"state": "live",
"replaced_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "queued",
"lane": "<string>",
"pages": 123,
"needs_review": true,
"review_reasons": [
"<string>"
],
"finalized": true,
"finalized_at": "2023-11-07T05:31:56Z",
"progress": {
"step": "<string>",
"questions_done": 123,
"questions_total": 123,
"estimated_ready_at": "2023-11-07T05:31:56Z"
},
"queue": {
"position": 123,
"estimated_ready_at": "2023-11-07T05:31:56Z"
},
"attempt_count": 123,
"rubric_version": 123,
"credits_charged": 123,
"error": {
"code": "<string>",
"message": "<string>"
},
"metadata": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "invalid_api_key",
"message": "The API key is not valid.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "insufficient_scope",
"message": "This API key lacks the evaluation:write scope.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f",
"details": {
"required_scope": "evaluation:write"
}
}
}{
"error": {
"code": "not_found",
"message": "The resource was not found.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "conflict",
"message": "The request conflicts with the current state.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "validation_failed",
"message": "questions[0].max_marks is required.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f",
"details": {
"errors": [
{
"field": "questions[0].max_marks",
"code": "required",
"message": "max_marks is required."
}
]
}
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests. Retry after 2 s.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}Review
Unfinalize a submission
Puts a finalized result back on hold so it can be reviewed or re-evaluated. reason is required and recorded. A submission that is not finalized returns 409 submission_not_finalized.
Scope: evaluation:finalize
POST
/
submissions
/
{submissionId}
/
unfinalize
Unfinalize a submission
curl --request POST \
--url https://api.evalezy.com/v1/submissions/{submissionId}/unfinalize \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"reason": "Revaluation request RV-2026-0193"
}
'import requests
url = "https://api.evalezy.com/v1/submissions/{submissionId}/unfinalize"
payload = { "reason": "Revaluation request RV-2026-0193" }
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({reason: 'Revaluation request RV-2026-0193'})
};
fetch('https://api.evalezy.com/v1/submissions/{submissionId}/unfinalize', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"exam_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"candidate": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"external_id": "<string>"
},
"state": "live",
"replaced_by": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "queued",
"lane": "<string>",
"pages": 123,
"needs_review": true,
"review_reasons": [
"<string>"
],
"finalized": true,
"finalized_at": "2023-11-07T05:31:56Z",
"progress": {
"step": "<string>",
"questions_done": 123,
"questions_total": 123,
"estimated_ready_at": "2023-11-07T05:31:56Z"
},
"queue": {
"position": 123,
"estimated_ready_at": "2023-11-07T05:31:56Z"
},
"attempt_count": 123,
"rubric_version": 123,
"credits_charged": 123,
"error": {
"code": "<string>",
"message": "<string>"
},
"metadata": {},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"error": {
"code": "invalid_api_key",
"message": "The API key is not valid.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "insufficient_scope",
"message": "This API key lacks the evaluation:write scope.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f",
"details": {
"required_scope": "evaluation:write"
}
}
}{
"error": {
"code": "not_found",
"message": "The resource was not found.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "conflict",
"message": "The request conflicts with the current state.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}{
"error": {
"code": "validation_failed",
"message": "questions[0].max_marks is required.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f",
"details": {
"errors": [
{
"field": "questions[0].max_marks",
"code": "required",
"message": "max_marks is required."
}
]
}
}
}{
"error": {
"code": "rate_limited",
"message": "Too many requests. Retry after 2 s.",
"request_id": "req_4f9c2a7e1b3d4c8a9e6f0b2d5a7c1e3f"
}
}Authorizations
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
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:
255Example:
"exam-cbse-sci-10a-2026-10-14"
Path Parameters
Submission id (UUID).
Body
application/json
Required, up to 500 characters (e.g. the revaluation request number).
Response
OK
Status of one submission. Create, get, lists and the feed all return this shape.
Show child attributes
Show child attributes
live for the current submission; replaced or deleted otherwise.
Example:
"live"
Present when this submission was replaced.
Available options:
queued, processing, reading, grading, graded, partially_graded, failed, cancelled copy (handwritten) or typed.
Page count of the handwritten copy.
Submission-level reasons, e.g. pages_beyond_vision_limit.
Show child attributes
Show child attributes
Only while queued.
Show child attributes
Show child attributes
How many evaluation runs this submission has had.
Charged credits once graded; 0 for a typed submission with only objective answers; null while running or when failed/cancelled.
Only when failed, e.g. copy_unreadable or language_not_supported.
Show child attributes
Show child attributes