Skip to content

For developers

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

Why OCR fails on student handwriting, what a production grading pipeline needs, build vs buy, and how the Evalezy API grades uploaded PDF answer sheets.

By the Evalezy team 8 min read

Key takeaways

  • Printed-text OCR is the wrong tool for student handwriting: even Tesseract’s own FAQ says it is designed for printed text.
  • A production grading pipeline is ten problems, not one: cleanup, line geometry, reading, answer location, rubric grading, validation, annotation, review, failure handling and billing.
  • Treat student writing as untrusted input: an answer can contain instructions aimed at the grader.
  • Build if grading is your core product or you need a script Evalezy has not tested; use an API if grading is a feature and you want marks plus a checked PDF.
  • The Evalezy API is asynchronous: create an exam, upload each answer sheet as a PDF, submit it, poll the submission feed (there are no webhooks yet), then read the draft marks and finalize them.

Your learners write on paper. Your product lives online. Somewhere between the two, a handwritten answer sheet has to become marks, feedback and something a learner actually wants to open. If you are a product manager or engineer adding that step to an edtech app, this post covers why plain OCR does not get you there, what a pipeline needs before you can trust it in production, how to think about building it yourself, and how the Evalezy API handles it.

Why printed-text OCR fails on student handwriting

Most OCR engines were built for print. Tesseract, the open-source OCR engine, says so in its own FAQ: you can use it for handwriting, but “it won’t work very well, as Tesseract is designed for printed text.” Handwriting is a harder problem because, as Wikipedia’s overview of the field puts it, “different people have different handwriting styles.”

Cloud document services do read handwriting, but check the language list before you plan around one. Microsoft’s Document Intelligence Read model lists Hindi, Marathi, Tamil and many other languages for printed text. Its v4.0 list for handwritten text has twelve languages, and none of them is an Indian language.

Student answer sheets then add problems of their own on top of the handwriting itself. These are the ones Evalezy’s pipeline is built to handle:

  • Phone photos, not scans. The sample copy on this site is a phone photo of a spiral notebook. Pages arrive tilted, shadowed and low in contrast. (Through the API, combine the photos into one PDF per answer sheet first.)
  • Answers out of order. Students answer Question 7 before Question 3, or number answers wrongly. A pipeline that trusts the written number marks the wrong answer.
  • Maths. Fractions, powers and working spread over several lines need a careful second look.
  • Long copies. A 20-page script has to be split into answers before anything can be graded.

And when reading fails, grading fails quietly. A grader handed garbled text has nothing true to grade. The pipeline must be able to say “this copy could not be read” instead of returning a mark.

What a robust pipeline needs

“Read the page, ask a model for a mark” is a demo. A version you can put in front of thousands of learners needs every stage below, and each one is a small project of its own.

Stages of a handwritten answer grading pipeline
StageWhat it doesWhat breaks without it
Page cleanupDeskews, denoises and boosts contrast on scans and phone photosFaint or tilted lines are misread or missed
Line geometryRecords where each line of writing sits on the pageTicks and notes land in the wrong place
Vision readingReads whole pages in context, with a second read for hard lines such as mathsWord fragments with no structure reach the grader
Answer locationFinds which pages hold which answer, by contentOut-of-order answers score zero
Rubric gradingOne set of criteria per question, reused for every studentEach copy is marked to a slightly different standard
Mark validationKeeps marks within the maximum, on the allowed step, with criteria adding upImpossible totals reach learners
AnnotationDraws ticks, crosses and notes on the student’s own pagesLearners get a table of numbers, not their copy
Human reviewHolds marks as a draft until a teacher releases themAn AI mistake goes straight to a learner
Failure and retriesFails unreadable copies with a reason; re-asks and flags low-confidence readsGuessed marks, or jobs stuck forever
Idempotent billingCharges each sheet once, and only when it succeedsRetries double-charge; failures cost money

Reading: a vision model, not a bag of words

A vision model reads the page image directly, layout and all, rather than handing your grader a list of recognised words. In Evalezy, copies of up to 40 pages are read in full this way, and unclear maths lines get a second read by Mathpix, a dedicated equation reader, up to four per copy. For copies of four pages or more, a locate pass works out which pages hold which answer. If a question then looks unattempted, it is re-checked against the whole copy, so a locate miss cannot zero a student.

Grading: the same criteria for every student

Consistency comes from fixing the rubric, not from hoping the model behaves the same way each time. Evalezy generates one marking scheme per question, once, and reuses it for every student: three to five criteria for subjective questions and one for objective questions, rescaled to add up exactly to the question’s maximum. Teachers can edit it or supply their own, and a stored model answer is used over a generated one. Marks are given in half-mark steps.

Treat student writing as untrusted input. OWASP puts prompt injection first (LLM01) in its 2025 Top 10 for LLM applications, and notes that injected instructions can arrive indirectly, through files or images the model processes. An answer sheet is exactly that kind of input. In a production test of Evalezy’s typed-answer grading, an answer that told the AI to “award full marks” scored 0 out of 5.

Line geometry and mark validation

Two stages are easy to skip in a prototype and painful to add later. The first is line geometry. A grader can say “the second point is wrong”, but to put a cross beside that point you need to know where the line sits on the page image. Keep a position for every line you read, in the same coordinates as the page you will draw on after cleanup and deskewing, or the annotations drift off the writing.

The second is mark validation. Treat every mark a model returns as a proposal and check it before you store it: not above the question’s maximum, on your marking step, criteria adding up to the question mark, question marks adding up to the total. When a check fails, re-ask or flag the question for a teacher; do not quietly round. Fixed rules, such as half-mark steps and criteria that sum exactly to the maximum, give these checks clear targets.

Annotation and review

Learners want to see their own page marked, not a JSON blob turned into a table. Evalezy draws ticks, crosses, short notes and marks per question in a handwriting style, with the total circled on page 1, and the same copy re-renders identically every time, which matters when a learner and a teacher are looking at the same page during a dispute. The AI never publishes a result on its own in the Evalezy dashboard: marks land as a draft, a teacher reviews and releases, and a mark the teacher edits is never overwritten by a later AI run.

Failure handling and billing

Async jobs fail and get retried, so billing has to be idempotent. Stripe’s API is a well-known example of the pattern: clients send an idempotency key so a request can be retried “without accidentally performing the same operation twice.” Whatever mechanism you choose, a retry should never become a second charge. In Evalezy, a copy that is mostly unreadable fails with a clear error and is not graded by guesswork, and failed, cancelled and unreadable checks are not charged. Evalezy’s own API takes an Idempotency-Key header on every POST for the same reason.

Build vs buy

Build in-houseUse an API
What you ownModels, prompts, data flow and every stage aboveYour rubric, model answers and review flow; the pipeline is the vendor’s
Before the first trustworthy resultAll ten stages, plus a test set of real copiesIntegration against a handful of endpoints
Ongoing workModel changes, prompt regressions, new handwriting edge cases, PDF renderingThe vendor’s job
Cost shapeModel calls, infrastructure and engineering time; per-page cost variesA fixed price per page, quoted before grading (Evalezy: ₹1 or $0.01); failed copies are free
Languages and scriptsWhatever you build and testEvalezy: English answers only for now; Hindi and regional languages are on the roadmap

Build if grading is your core product, if you need a language or script now that no vendor has tested, or if answer sheets must never leave your own infrastructure. Use an API if grading is one feature of a larger product, if you want a checked PDF and a review step without building them, and if a per-page cost is easier to plan for than a team. If you are weighing a general chatbot instead, our comparison with ChatGPT covers that approach.

Either way, decide on evidence. Collect a test set of real answer sheets from your own learners, say fifty copies across neat and messy handwriting, phone photos and scans, and have experienced teachers mark them first. Run them through your prototype or a vendor and compare question by question: where marks differ, whether the reasons make sense, and which copies failed. Keep that set. It becomes your regression test for every model or prompt change afterwards.

How the Evalezy API works

The Evaluation API went live on 2 October 2026 at https://api.evalezy.com/v1, with full documentation at docs.evalezy.com. It is JSON over HTTPS, and every request carries your key in an X-API-Key header. It grades handwritten copies and typed long answers.

  1. 1

    Create the exam

    POST /exams with the questions, max marks, answer keys for objective questions and a rubric or model answer for each long answer, with mode set to handwritten (or typed, for typed answers). Send open: true to accept submissions straight away. Rubric criteria must add up exactly to the question’s marks, or the request is refused. A long answer with neither a rubric nor a model answer gets a rubric generated on the first copy, reused for every candidate.

  2. 2

    Upload each answer sheet

    POST /uploads returns a short-lived presigned URL for each PDF, up to 100 files per call. PUT the file to that URL, without your API key. Read GET /uploads/{id} if you want to see the page count before you submit. One PDF per answer sheet, up to 50 MB.

  3. 3

    Submit the copy

    POST /exams/{id}/submissions with the candidate, named by your own external_id, and the upload_id. You get 202 Accepted with the submission id, status queued, a queue position, an estimated ready time and a fixed-price quote. Typed exams send answers[] instead of an upload.

  4. 4

    Follow grading

    Each submission moves through queued, processing, reading and grading, and ends as graded, partially_graded, failed or cancelled. There are no webhooks yet: poll GET /submissions/{id} for one copy, or the feed GET /submissions?updated_since= for every change across your exams.

  5. 5

    Read the result

    GET /submissions/{id}/result gives the totals and, per question, awarded and max marks, criteria with reasons, feedback, the extracted answer, a confidence score and needs_review. GET /submissions/{id}/checked-copy downloads the red-pen PDF.

  6. 6

    Review, then finalize

    A teacher overrides a question’s marks (free) or approves the copy, either in your product through the review endpoints or in the Vacademy dashboard, where exams created through the API appear tagged Source: API. POST /exams/{id}/finalize then turns the draft marks into final marks.

Here is the core of an integration in Node.js 18 or later. The first part creates the exam, uploads one student’s PDF and submits it:

// Node.js 18+, run as an ES module. Call Evalezy from your server only.
import { readFile, stat } from "node:fs/promises";

const API = "https://api.evalezy.com/v1";

async function call(method, path, body, idempotencyKey) {
  const res = await fetch(API + path, {
    method,
    headers: {
      "X-API-Key": process.env.EVALEZY_API_KEY,
      "Content-Type": "application/json",
      ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const json = await res.json();
  if (!res.ok) throw new Error(res.status + " " + json.error.code + ": " + json.error.message);
  return json;
}

// 1. Create the exam once and open it. Criteria must add up to max_marks.
const exam = await call("POST", "/exams", {
  title: "Social Science · Half-Yearly Mock Test 4",
  mode: "handwritten",
  external_ref: "sst-ix-mock-4",
  open: true,
  questions: [
    {
      label: "30", type: "long_answer", max_marks: 3,
      text: "Explain the factors affecting climate.",
      rubric: { 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 },
      ] },
    },
    // ...one entry per question on the paper
  ],
}, "exam-sst-ix-mock-4");

// 2. Ask for a presigned upload URL, then PUT the PDF to it (no API key on the PUT)
const file = "scans/IXB-14.pdf";
const { uploads: [upload] } = await call("POST", "/uploads", {
  filename: "IXB-14.pdf",
  content_type: "application/pdf",
  size_bytes: (await stat(file)).size,
});
const put = await fetch(upload.upload_url, {
  method: "PUT", headers: upload.headers, body: await readFile(file),
});
if (!put.ok) throw new Error("Upload failed: " + put.status);

// 3. Submit it, naming the student by your own id. 202 Accepted, price fixed now.
const sub = await call("POST", "/exams/" + exam.id + "/submissions", {
  candidate: { external_id: "IXB-14", name: "Aditi Sharma", roll_number: "14" },
  upload_id: upload.id,
}, "sst-ix-mock-4-IXB-14");
console.log(sub.status, sub.quote); // "queued" { unit: "page", pages: 7, credits: 7, ... }

The second part is a worker you run every 30 to 60 seconds. It reads the feed of every submission that changed, across all your exams, and fetches the result of each copy that has finished. Each pass starts two minutes before the last updated_at it processed, so a change saved a moment late is not missed:

// 4. No webhooks yet: poll the feed of every submission that changed.
//    Run a pass every 30 to 60 seconds and save the watermark it returns.
//    On the first run, pass a time before your first submission.
async function syncOnce(watermark) {
  const since = new Date(Date.parse(watermark) - 2 * 60 * 1000).toISOString();
  const params = new URLSearchParams({ updated_since: since, limit: "200" });
  for (;;) {
    const page = await call("GET", "/submissions?" + params);
    for (const row of page.data) {
      if (Date.parse(row.updated_at) > Date.parse(watermark)) watermark = row.updated_at;
      if (row.state !== "live") continue; // replaced or deleted: mark it so on your side
      if (row.status === "graded" || row.status === "partially_graded") {
        // 5. Draft marks, criteria with reasons, feedback, confidence, needs_review
        const result = await call("GET", "/submissions/" + row.id + "/result");
        await saveResult(row, result); // your upsert, keyed by row.id
      } else if (row.status === "failed") {
        await saveFailure(row, row.error.code); // e.g. copy_unreadable; not charged
      }
    }
    if (!page.has_more) return watermark;
    params.set("cursor", page.next_cursor);
  }
}

// 6. After a teacher's review, in your app or the Vacademy dashboard, make the marks final.
//    This call needs a key with the evaluation:finalize scope. all_graded covers "graded"
//    copies only; finalize partially_graded ones by id with allow_partial: true once a
//    teacher has marked the questions the AI could not grade.
await call("POST", "/exams/" + exam.id + "/finalize", { all_graded: true });

New keys get the read and write scopes. Finalizing needs the evaluation:finalize scope, and overriding or approving marks needs evaluation:review, so a system that only sends copies never gets to publish marks. The example values come from the real sample copy, a 7-page Class IX Social Science answer sheet that scored 38 out of 80; at 1 credit a page, it costs 7 credits.

The docs have the same flow in curl, Python and Node: the quickstart, the handwritten exams guide and a complete sync worker with retries in Syncing results.

Shipping it in your product

  • Keep the key on your server. The API is server-to-server only. Anyone with the key can spend your credits, so your app talks to your backend and your backend talks to Evalezy. Use one key per system and environment, with only the scopes it needs.
  • Show the checked copy, not only the JSON. The checked copy is what learners open and share. Your server can fetch it from GET /submissions/{id}/checked-copy whenever a learner asks, so you need not store it. Put it first; use the per-question data for progress tracking and reports.
  • Put a reviewer before the learner. The API returns draft marks with reasons, and needs_review flags what the AI was unsure about, for example a confidence below 0.60. Nothing is final until you call finalize. Teachers can review in your own screens, or in the Vacademy dashboard, where API exams appear tagged Source: API and their changes show up in your results. We recommend that a teacher looks first, as in Evalezy’s own teacher review.
  • Map results to your users. Send your own student id as candidate.external_id on every submission, and your own answer-sheet id in metadata if you need it, so every row in the feed maps straight back to the right learner.
  • Make retries safe. Send an Idempotency-Key on every POST: a retry with the same key returns the stored response instead of creating or charging a second submission. A candidate has one live submission per exam, so a duplicate is refused with 409 submission_exists; send replace: true when you do mean to send a new copy.
  • Design for minutes, not seconds. A handwritten copy typically takes a few minutes, and longer copies take longer. Each submission carries an estimated ready time. Show progress, let the learner leave and notify them when the result is ready.
  • Handle failure honestly. When a copy fails as copy_unreadable, ask the learner for a clearer scan and send it with replace: true, rather than showing a zero. Failed copies are not charged.
  • Know the limits. One PDF per answer sheet, up to 50 MB; phone photos must be combined into a PDF first. English answers only for now. Diagrams, maps and graphs are judged by their labels and written explanation, not as drawings.
  • Budget per page. A 5-page copy is 5 credits, blank pages included, which is ₹5 or $0.05 at the standard rate. POST /credits/quote prices a whole exam before you submit it. Re-evaluating a copy is charged again, so re-evaluate deliberately.

Before your first real exam, run through the docs’ going-live checklist (keys, quotas and rate limits), and check the roadmap for what is not available yet.

Where Evalezy fits

Evalezy handles the reading, grading, annotation and review stages for you, in a dashboard or through the API. Upload a handwritten answer sheet as a PDF, or send typed answers, and get back per-question marks, criteria with reasons, feedback, the student’s answer as read and a red-pen checked PDF, as drafts until you finalize them.

Same price as the dashboard. 1 credit per page, quoted before grading: ₹1 in India (excluding GST) or $0.01 elsewhere. Typed long answers are 1 credit each and objective answers are free. Failed and cancelled copies are not charged. See pricing.

Your rubric, checked when you send it. Send your own criteria or a model answer for each question; criteria that do not add up to the question’s marks are refused, not quietly rescaled. Leave both out and a rubric is generated on the first copy and reused for every candidate, and you can read it back and replace it. See the API page, the API docs and the edtech platforms page.

Book a demo

Sources

  1. Tesseract documentation, FAQ: “Can I use Tesseract for handwriting recognition?” (checked 1 October 2026)
  2. Wikipedia, Handwriting recognition (offline recognition and handwriting styles) (checked 1 October 2026)
  3. Microsoft Learn, Language and locale support for Read and Layout document analysis (Document Intelligence v4.0) (checked 1 October 2026)
  4. OWASP Gen AI Security Project, LLM01:2025 Prompt Injection (checked 1 October 2026)
  5. Stripe API reference, Idempotent requests (checked 1 October 2026)
  6. Evalezy API documentation (introduction, authentication, submissions, results, pricing and roadmap) (checked 2 October 2026)

Frequently asked questions

Can I grade handwritten answers with Tesseract or another OCR library?+

You can extract some text, but Tesseract’s own FAQ says it will not work very well on handwriting because it is designed for printed text. Grading also needs answer location, a rubric, validation and annotation on top of reading, so OCR is at most one stage of the pipeline.

Why not send the page straight to a general chatbot?+

A single chat prompt gives you a mark, but not a fixed rubric reused for every student, mark validation, a checked PDF, a review step or clear failure on unreadable pages. We compare the two approaches on the Evalezy vs ChatGPT page.

Is the Evalezy API synchronous?+

No. POST /exams/{id}/submissions answers 202 Accepted straight away, with a submission id, a queue position, an estimated ready time and a fixed-price quote. A handwritten copy typically takes a few minutes, and longer copies take longer. There are no webhooks yet: poll GET /submissions/{id} for one copy, or the feed GET /submissions?updated_since= for everything that changed since your last check.

What does a graded submission return?+

GET /submissions/{id}/result returns the totals and, for each question, the marks awarded out of the maximum, the marks and a reason for each rubric criterion, feedback, the text Evalezy read from the copy, a confidence from 0 to 1 and a needs_review flag. GET /submissions/{id}/checked-copy downloads the student’s PDF with the marks and notes on it. All marks are drafts until you call finalize.

How is the API billed?+

In credits, at a fixed price quoted before grading starts: 1 credit per page of a handwritten PDF, blank pages included, and 1 credit per non-blank typed long answer. Objective answers are free. Failed and cancelled copies are not charged; re-evaluating a copy is charged again. Credits are bought in the Vacademy dashboard. At the standard rate a page costs ₹1 in India (excluding GST) or $0.01 elsewhere, the same as the dashboard.

Is there a sandbox or test mode?+

No. Every key is live and every graded copy is charged. Test with a small exam and one or two short copies. Typed submissions with only objective answers are free, so you can try exam setup and the submission flow without spending credits.

Can I send phone photos, or a link to the answer sheet?+

Not yet. The API takes one PDF per answer sheet, up to 50 MB, uploaded through a presigned URL from POST /uploads. Combine phone photos into one PDF first. Copies of up to 40 pages are graded normally, copies of 41 to 80 pages are graded and flagged for review, and longer ones are refused before any charge.

Does it read Hindi or other Indian-language handwriting?+

Not yet. The API grades English answers only for now: a handwritten copy written in Hindi or another regional language fails with language_not_supported and is not charged. Hindi and regional languages are on the API roadmap; if you need them, tell us at [email protected], since partner demand sets the order.

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.