Evaluation API

Answer sheet evaluation, as an API.

Send a handwritten answer sheet by file or URL. Get back per-question marks, feedback, the student's answer as read and a red-pen checked PDF. Same engine and same price as the Evalezy dashboard: ₹1 / $0.01 per page.

Book a demo Request API access

POST /evaluations

curl https://api.evalezy.com/v1/evaluations \
  -H "Authorization: Bearer $EVALEZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assessment_id": "asm_7Hq2",
    "answer_sheet_url": "https://files.example.edu/ix-b/roll-14.pdf",
    "student": { "external_id": "IXB-14" },
    "webhook_url": "https://api.example.edu/hooks/evalezy"
  }'

Bearer API keys

Every request carries Authorization: Bearer <key>. Base URL: https://api.evalezy.com/v1

Webhooks or polling

Pass a webhook_url per evaluation, or poll GET /evaluations/{id} for status and progress.

Billed on success

Charged per page only when an evaluation completes. Failed, cancelled and unreadable: free.

The flow

Create an assessment

Send your questions with marks, or a question paper URL to be read into questions. You get back an assessment id and the question list.

POST /assessments

curl https://api.evalezy.com/v1/assessments \
  -H "Authorization: Bearer $EVALEZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Social Science · Half-Yearly Mock Test 4",
    "class": "IX",
    "question_paper_url": "https://files.example.edu/papers/sst-ix-mock-4.pdf"
  }'

Set evaluation criteria

Send criteria and an optional model answer per question. Criteria marks are rescaled to sum to the question's marks. Or call /criteria/generate for a draft to edit.

PUT /assessments/{id}/criteria

curl -X PUT https://api.evalezy.com/v1/assessments/asm_7Hq2/criteria \
  -H "Authorization: Bearer $EVALEZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "questions": [{
      "question_id": "q_30",
      "max_marks": 3,
      "model_answer": "Latitude, altitude, pressure and wind system, distance from the sea, ocean currents, relief.",
      "criteria": [
        { "name": "Names valid factors of climate", "marks": 1.5 },
        { "name": "Explains how each factor affects climate", "marks": 1 },
        { "name": "Uses a correct example", "marks": 0.5 }
      ]
    }]
  }'

Send an answer sheet

Pass a URL to the PDF, or upload it to /files first and send the file id. Include your own student id so results map back to your users.

POST /evaluations

curl https://api.evalezy.com/v1/evaluations \
  -H "Authorization: Bearer $EVALEZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assessment_id": "asm_7Hq2",
    "answer_sheet_url": "https://files.example.edu/ix-b/roll-14.pdf",
    "student": { "external_id": "IXB-14" },
    "webhook_url": "https://api.example.edu/hooks/evalezy"
  }'

202 Accepted

{
  "id": "ev_3kP9xW",
  "status": "queued",
  "assessment_id": "asm_7Hq2",
  "student": { "external_id": "IXB-14" }
}

Get the result

Poll the evaluation or wait for the webhook. A completed evaluation carries the total, every question's marks, the student's answer as read, feedback, the criteria breakdown and the checked PDF.

Example values are from the real sample copy (38/80).

GET /evaluations/ev_3kP9xW → 200

{
  "id": "ev_3kP9xW",
  "status": "completed",
  "pages": 7,
  "total": { "awarded": 38, "max": 80 },
  "questions": [
    {
      "number": "4",
      "awarded": 0,
      "max": 1,
      "student_answer": "Temperature",
      "feedback": "Wrong answer. Correct: latitude (distance from the equator)."
    },
    {
      "number": "30",
      "awarded": 0.5,
      "max": 3,
      "student_answer": "1. Temperature 2. Humidity 3. Precipitation 4. Atmospheric Pressure 5. Wind",
      "feedback": "Only weather elements listed; no factors of climate explained.",
      "criteria": [
        { "name": "Names valid factors of climate", "awarded": 0.5, "max": 1.5 },
        { "name": "Explains how each factor affects climate", "awarded": 0, "max": 1 },
        { "name": "Uses a correct example", "awarded": 0, "max": 0.5 }
      ]
    }
  ],
  "checked_copy_url": "https://files.evalezy.com/ev_3kP9xW/checked-copy.pdf",
  "billing": { "pages": 7, "amount": 7, "currency": "INR" }
}

Endpoints

Base URL https://api.evalezy.com/v1

Method	Path	What it does
POST	/assessments	Create an assessment from a list of questions with marks, or from a question paper URL to be read into questions.
GET	/assessments/{id}	Fetch an assessment with its questions, marks and current criteria.
PUT	/assessments/{id}/criteria	Set evaluation criteria and model answers per question. Criteria marks are rescaled to sum to the question's marks.
POST	/assessments/{id}/criteria/generate	Ask Evalezy to draft criteria for every question; review and edit before you evaluate.
POST	/files	Upload an answer sheet PDF (multipart). Returns a file id to evaluate.
POST	/evaluations	Start checking one answer sheet, by file id or public URL, with your student id and an optional webhook.
GET	/evaluations/{id}	Status, progress and, once completed, marks per question, feedback and the checked copy PDF URL.
POST	/evaluations/{id}/cancel	Stop a running evaluation. Cancelled evaluations are not billed.

Statuses

queuedAccepted and waiting for a slot.
readingPages are being read: layout, handwriting, maths lines.
gradingQuestions are being marked; progress shows questions done / total.
completedMarks, feedback and the checked PDF are ready.
failedCould not be checked, e.g. an unreadable copy. Reason included. Not billed.
cancelledStopped by you. Not billed.

Webhooks

Pass webhook_url when you create an evaluation and Evalezy posts to it when the evaluation completes or fails. Fetch the full result with the id.

evaluation.completed

POST https://api.example.edu/hooks/evalezy
{
  "event": "evaluation.completed",
  "evaluation_id": "ev_3kP9xW",
  "status": "completed",
  "total": { "awarded": 38, "max": 80 }
}

Answer sheets that cannot be read fail with a reason and are not billed
Cancel any running evaluation; cancelled evaluations are not billed
Each evaluation is billed once, even if it is retried internally

Ready to build?

Tell us what you are building and your expected volume. We will enable API access on your account.

Request API access

Frequently asked questions

How do I get an API key?+

API access is enabled per account. Request it on the demo page with your use case and expected monthly volume.

Is the API synchronous?+

No. Checking takes minutes, so evaluations are asynchronous: create one, get an id back immediately, then poll the status endpoint or receive a webhook.

What file formats are accepted?+

PDF answer sheets, one file per student, uploaded directly or fetched from a URL you provide. Phone photos combined into a PDF work.

How is the API billed?+

Per page checked: ₹1 in India, $0.01 elsewhere. Failed, cancelled and unreadable sheets are not billed.

Can I get the checked PDF?+

Yes. A completed evaluation includes a URL to the checked copy with ticks, crosses, notes, marks and the circled total.

Do teachers still review API results?+

That is up to your product. The API returns the AI's marks with the reason for each; most platforms show them to a teacher or reviewer before learners see them.

From the blog

For developers

Handwritten Answer Grading API: OCR, Vision Models, Build vs Buy

See your own copies checked.

Book a 20-minute demo. Bring a question paper and a few scanned answer sheets, and watch Evalezy check them in red pen.

Book a demo See a real checked copy