Upload an exam answer sheet

PATCH

evaluation-platform

exam

{examId}

answer-sheet

{id}

cURL

SHEET=https://api.crazygoldfish.com/evaluation-platform/v1/exam/d19e6868-98dd-4274-a2a5-4a616dd93ea7/answer-sheet/8a2f4c1e-5b3d-4e6f-9a7b-0c1d2e3f4a5b/

# 1. Upload the pages, in order
curl -X PATCH "$SHEET" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F documents=@page-1.jpg \
  -F documents=@page-2.jpg

# 2. Submit for evaluation
curl -X PATCH "$SHEET" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"isFinal": true}'

import requests

BASE_URL = "https://api.crazygoldfish.com"
HEADERS = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
sheet_url = (
    f"{BASE_URL}/evaluation-platform/v1/exam/d19e6868-98dd-4274-a2a5-4a616dd93ea7"
    f"/answer-sheet/8a2f4c1e-5b3d-4e6f-9a7b-0c1d2e3f4a5b/"
)

handles = [
    open(name, "rb") for name in ["page-1.jpg", "page-2.jpg"]
]
pages = [
    ("documents", (handle.name, handle, "image/jpeg"))
    for handle in handles
]
try:
    requests.patch(
        sheet_url, headers=HEADERS, files=pages
    ).raise_for_status()
finally:
    for handle in handles:
        handle.close()

requests.patch(
    sheet_url, headers=HEADERS, json={"isFinal": True}
).raise_for_status()

import { openAsBlob } from "node:fs"; // Node 20 or later

const BASE_URL = "https://api.crazygoldfish.com";
const HEADERS = { Authorization: "Bearer YOUR_ACCESS_TOKEN" };
const sheetUrl =
  `${BASE_URL}/evaluation-platform/v1/exam/d19e6868-98dd-4274-a2a5-4a616dd93ea7` +
  `/answer-sheet/8a2f4c1e-5b3d-4e6f-9a7b-0c1d2e3f4a5b/`;

const form = new FormData();
for (const name of ["page-1.jpg", "page-2.jpg"]) {
  const page = await openAsBlob(name, { type: "image/jpeg" });
  form.append("documents", page, name);
}
let response = await fetch(sheetUrl, {
  method: "PATCH",
  headers: HEADERS,
  body: form,
});
if (!response.ok) throw new Error(await response.text());

response = await fetch(sheetUrl, {
  method: "PATCH",
  headers: { ...HEADERS, "Content-Type": "application/json" },
  body: JSON.stringify({ isFinal: true }),
});
if (!response.ok) throw new Error(await response.text());

{
  "id": "8a2f4c1e-5b3d-4e6f-9a7b-0c1d2e3f4a5b",
  "documents": [
    {
      "id": "c6d1e0f9-3a52-4b87-9d64-5e1f2a3b4c5d",
      "status": 0,
      "pageNo": null,
      "uploadTime": "2026-03-18T09:14:02.481293Z",
      "url": "https://<storage-host>/media/evaluation/page-1.jpg",
      "fileType": 3
    }
  ],
  "studentId": "S-2043",
  "instituteId": "SCH-17",
  "teacherId": "T-1042",
  "studentName": "Aarav Sharma",
  "parentId": "P-9981"
}

Step 5 of 8 in Evaluate an exam. Call it twice: once to upload, once with isFinal to submit.

Rules

Send exactly one of documents, fileUrl, or isFinal per request.
Files must be .pdf, .jpg, .jpeg, or .png, and at most 20 MB each.
Declare each file’s type in its multipart part: application/pdf, image/jpeg, or image/png. The API reads the part’s Content-Type, not the file name. Most other values are rejected with 400 Invalid file type, but the Word .docx type is not, so do not send one by accident.
A PDF can have at most 50 pages, and a sheet takes one PDF. You cannot mix a PDF with images.
Upload images in page order. You can send them in one call or across several, and each call adds to what is there.
Every uploaded file goes through a readability check. A page the checker cannot read is rejected with 400, so scan or photograph pages in good light. The 400 occasionally arrives with an empty message: treat it as a rejected file and upload the page again. A fileUrl skips the check.
Send {"isFinal": true} once all the pages are uploaded. That starts evaluation.

In a multipart request, any value of isFinal submits the sheet, including isFinal=false. Leave the field out until you mean it, and use JSON when you submit.

Submitting counts against a daily limit for your API user and returns 429 Rate limit exceeded once you reach it. Rejected requests count too, and the limit resets at 00:01 server time.

Files are only accepted while the sheet is Open. Once evaluation is running or has failed, the call still returns 200 and quietly ignores the files. Submitting a sheet with no files returns 404 No documents found for this answer sheet, not 400.

How to know when it’s done

The response has no status field of its own. Two things tell you where evaluation is:

Signal	Meaning
`documents[].status`	`0` Open, `1` In Progress, `2` Completed, `3` Failed for that one file. Also in List exam answer sheets.
Get exam scores for review	Returns `400` until the sheet is graded, then `200`

Or register a webhook for exam_evaluation_student_answer_sheet_evaluation. See Async jobs and webhooks.

Next step

Get exam scores for review

Read the marks and feedback before anyone else sees them.

Authorizations

Authorization

string

header

required

Access token from Get an access token. A missing, invalid, or expired token returns 403.

Path Parameters

examId

string<uuid>

required

The exam id returned by Create an exam. Write it in lowercase: this path only matches lowercase hexadecimal characters and hyphens.

Example:

"d19e6868-98dd-4274-a2a5-4a616dd93ea7"

string<uuid>

required

The answer sheet id returned by Create an exam answer sheet.

Example:

"8a2f4c1e-5b3d-4e6f-9a7b-0c1d2e3f4a5b"

Body

documents

file[]

Scans or photos of the student's answer sheet. One .pdf of up to 50 pages, or any number of .jpg and .png images, in page order. Up to 20 MB per file. Each part's Content-Type decides the file type, so declare application/pdf, image/jpeg, or image/png. No mixing a PDF with images, and one PDF per sheet.

fileUrl

string<uri>

Public HTTPS link to a PDF instead of an upload. The API fetches it and rejects anything that does not start with %PDF.

Example:

"https://example.com/sheets/s-2043.pdf"

isFinal

boolean

Send true to submit the sheet for evaluation. Send it on its own. In a multipart request any value, including false, submits the sheet, so leave the field out until you mean it.

Response

The answer sheet was updated. With isFinal=true, evaluation has started.

One student's answer sheet. It never reports a status of its own.

string<uuid>

The answer sheet ID.

documents

object[]

Files attached to the answer sheet, oldest first.

Show child attributes

studentId

string | null

Your own student reference.

instituteId

string | null

Your own school or institute reference.

teacherId

string | null

Your own teacher reference.

studentName

string | null

parentId

string | null

Your own parent reference.

cURL

SHEET=https://api.crazygoldfish.com/evaluation-platform/v1/exam/d19e6868-98dd-4274-a2a5-4a616dd93ea7/answer-sheet/8a2f4c1e-5b3d-4e6f-9a7b-0c1d2e3f4a5b/

# 1. Upload the pages, in order
curl -X PATCH "$SHEET" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F documents=@page-1.jpg \
  -F documents=@page-2.jpg

# 2. Submit for evaluation
curl -X PATCH "$SHEET" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"isFinal": true}'

import requests

BASE_URL = "https://api.crazygoldfish.com"
HEADERS = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
sheet_url = (
    f"{BASE_URL}/evaluation-platform/v1/exam/d19e6868-98dd-4274-a2a5-4a616dd93ea7"
    f"/answer-sheet/8a2f4c1e-5b3d-4e6f-9a7b-0c1d2e3f4a5b/"
)

handles = [
    open(name, "rb") for name in ["page-1.jpg", "page-2.jpg"]
]
pages = [
    ("documents", (handle.name, handle, "image/jpeg"))
    for handle in handles
]
try:
    requests.patch(
        sheet_url, headers=HEADERS, files=pages
    ).raise_for_status()
finally:
    for handle in handles:
        handle.close()

requests.patch(
    sheet_url, headers=HEADERS, json={"isFinal": True}
).raise_for_status()

import { openAsBlob } from "node:fs"; // Node 20 or later

const BASE_URL = "https://api.crazygoldfish.com";
const HEADERS = { Authorization: "Bearer YOUR_ACCESS_TOKEN" };
const sheetUrl =
  `${BASE_URL}/evaluation-platform/v1/exam/d19e6868-98dd-4274-a2a5-4a616dd93ea7` +
  `/answer-sheet/8a2f4c1e-5b3d-4e6f-9a7b-0c1d2e3f4a5b/`;

const form = new FormData();
for (const name of ["page-1.jpg", "page-2.jpg"]) {
  const page = await openAsBlob(name, { type: "image/jpeg" });
  form.append("documents", page, name);
}
let response = await fetch(sheetUrl, {
  method: "PATCH",
  headers: HEADERS,
  body: form,
});
if (!response.ok) throw new Error(await response.text());

response = await fetch(sheetUrl, {
  method: "PATCH",
  headers: { ...HEADERS, "Content-Type": "application/json" },
  body: JSON.stringify({ isFinal: true }),
});
if (!response.ok) throw new Error(await response.text());

{
  "id": "8a2f4c1e-5b3d-4e6f-9a7b-0c1d2e3f4a5b",
  "documents": [
    {
      "id": "c6d1e0f9-3a52-4b87-9d64-5e1f2a3b4c5d",
      "status": 0,
      "pageNo": null,
      "uploadTime": "2026-03-18T09:14:02.481293Z",
      "url": "https://<storage-host>/media/evaluation/page-1.jpg",
      "fileType": 3
    }
  ],
  "studentId": "S-2043",
  "instituteId": "SCH-17",
  "teacherId": "T-1042",
  "studentName": "Aarav Sharma",
  "parentId": "P-9981"
}

Get started

Guides

Exam Evaluation

Assignment Evaluation

Rubrics

Action Plans

Lesson Plan Builder

Worksheet Builder

ClassTrack

Metadata

Webhooks

Upload an exam answer sheet

Rules

How to know when it’s done

Next step

Get exam scores for review

Authorizations

Path Parameters

Body

Response

​Rules

​How to know when it’s done

​Next step

Get exam scores for review

Authorizations

Path Parameters

Body

Response

Rules

How to know when it’s done

Next step