Skip to content

Evaluation API

Answer sheet evaluation, as an API.

Grade handwritten answer copies and typed long answers from your own exam system. Send a question paper, a marking scheme and each candidate's PDF; get back question-wise marks, reasons, feedback and the checked copy in red pen. Marks stay drafts until you finalize them.
POST /exams/{id}/submissions
curl https://api.evalezy.com/v1/exams/$EXAM_ID/submissions \
  -H "X-API-Key: $EVALEZY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sst-ix-mock-4-IXB-14" \
  -d '{
    "candidate": { "external_id": "IXB-14", "name": "Aditi Sharma", "roll_number": "14" },
    "upload_id": "0d2b6c1e-6a1f-4c55-9a43-2b1f0c9e7a10"
  }'

X-API-Key, scoped

Keys look like vak_eval_… and carry scopes: read, write, review, finalize. Server to server only. Base URL https://api.evalezy.com/v1

Fixed price, quoted first

1 credit per page (handwritten) or per long answer (typed). POST /credits/quote before you submit; failed and cancelled are free.

Safe retries

Idempotency-Key on every POST, plus natural keys: your external_ref per exam, external_id per candidate, one live submission each.

Drafts until you finalize

The AI never publishes marks. Override, approve, then POST /exams/{id}/finalize. Unfinalizing needs a reason.

Dashboard review included

API exams show up in the Vacademy dashboard, tagged Source: API, so teachers can review without you building a screen.

Full reference and guides

Every endpoint with request, response and code, guides for term exams, typed tests and daily answer writing, and an OpenAPI document.

The flow, in six calls

Ten-minute quickstart
  1. 1.

    Create an exam

    Questions, max marks, answer keys for objective questions and a rubric or model answer for long answers. Opening it fixes the questions, marks and answer keys; rubrics and model answers stay editable.

    In the docs
    POST /exams
    curl https://api.evalezy.com/v1/exams \
      -H "X-API-Key: $EVALEZY_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: sst-ix-mock-4" \
      -d '{
        "title": "Social Science · Half-Yearly Mock Test 4",
        "mode": "handwritten",
        "external_ref": "sst-ix-mock-4",
        "class": "9",
        "open": true,
        "questions": [{
          "label": "30",
          "type": "long_answer",
          "text": "Explain the factors affecting climate.",
          "max_marks": 3,
          "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 }
          ]}
        }]
      }'
  2. 2.

    Upload the answer sheets

    One PDF per candidate. Ask for presigned URLs (up to 100 per call), PUT each file, then read the upload back to confirm its page count.

    In the docs
    POST /uploads
    # 1. Ask for a presigned upload URL (1 to 100 PDFs per call, 50 MB each)
    curl https://api.evalezy.com/v1/uploads \
      -H "X-API-Key: $EVALEZY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"filename": "IXB-14.pdf", "content_type": "application/pdf", "size_bytes": 8421337}'
    
    # 2. PUT the PDF to the upload_url it returns (no API key on this call)
    curl -X PUT "$UPLOAD_URL" -H "Content-Type: application/pdf" --data-binary @IXB-14.pdf
  3. 3.

    Submit each copy

    Name the candidate by your own id and pass the upload_id; typed tests send answers[] instead. You get 202 and a fixed-price quote straight away.

    In the docs
    POST /exams/{id}/submissions
    curl https://api.evalezy.com/v1/exams/$EXAM_ID/submissions \
      -H "X-API-Key: $EVALEZY_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: sst-ix-mock-4-IXB-14" \
      -d '{
        "candidate": { "external_id": "IXB-14", "name": "Aditi Sharma", "roll_number": "14" },
        "upload_id": "0d2b6c1e-6a1f-4c55-9a43-2b1f0c9e7a10"
      }'
  4. 4.

    Follow grading

    Poll one submission, or the feed of everything that changed since your last sync. Webhooks are on the roadmap; polling is the supported way today.

    In the docs
    GET /submissions?updated_since=
    # No webhooks yet: poll the feed and follow next_cursor until has_more is false
    curl "https://api.evalezy.com/v1/submissions?updated_since=2026-10-02T10:00:00Z" \
      -H "X-API-Key: $EVALEZY_API_KEY"
  5. 5.

    Read results and the checked copy

    Question-wise marks, criteria with reasons, feedback, the answer as read, confidence and needs_review, plus the red-pen PDF.

    In the docs
    GET /submissions/{id}/result → 200
    {
      "submission_id": "5a7e2c90-1b4d-4e8f-a3c2-7d9e0f1a2b3c",
      "status": "graded",
      "needs_review": true,
      "finalized": false,
      "totals": { "awarded": 38, "max": 80, "percentage": 47.5 },
      "questions": [
        {
          "label": "30",
          "awarded": 0.5,
          "max": 3,
          "source": "ai",
          "confidence": 0.88,
          "needs_review": false,
          "extracted_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, "reason": "Lists weather elements, not factors." },
            { "name": "Explains how each factor affects climate", "awarded": 0, "max": 1, "reason": "No explanation." },
            { "name": "Uses a correct example", "awarded": 0, "max": 0.5, "reason": "No example." }
          ]
        }
      ],
      "checked_copy": { "available": true, "download_path": "/submissions/5a7e2c90-…/checked-copy" },
      "credits_charged": 7
    }
  6. 6.

    Review, then finalize

    Override any mark (free) or approve it, in your app or in the Vacademy dashboard. Marks are drafts until you finalize.

    In the docs
    POST /exams/{id}/finalize
    curl -X POST https://api.evalezy.com/v1/exams/$EXAM_ID/finalize \
      -H "X-API-Key: $EVALEZY_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"all_graded": true}'

Example values come from the real sample copy on this site (Class IX Social Science, 7 pages, 38/80).

Key endpoints

Full API reference

Base URL https://api.evalezy.com/v1. These are the calls most integrations use; the reference lists all of them.

MethodPathWhat it does
POST/examsCreate an exam with its questions, marks, answer keys and rubrics or model answers. Send open: true to accept submissions straight away.
POST/exams/{id}/openOpen a draft exam to accept copies. Rubrics must add up to max marks; questions, marks and answer keys are then fixed.
PUT/exams/{id}/questions/{qid}/rubricSet one long-answer question's rubric and model answer. Without one, a rubric is generated on the first copy and reused.
POST/candidatesCreate or update up to 2,000 candidates by your own external_id. Or skip it and send the candidate with the submission.
POST/uploadsGet presigned URLs for 1 to 100 PDFs (50 MB each), PUT each file, then read it back to check its page count.
POST/exams/{id}/submissionsSubmit one candidate's copy (upload_id) or typed answers. Returns 202 with a fixed-price quote.
GET/submissions?updated_since=…The feed of every submission that changed, across exams. Poll it to pick up results (no webhooks yet).
GET/submissions/{id}/resultQuestion-wise marks, criteria with reasons, feedback, the answer as read, confidence and needs_review.
GET/submissions/{id}/checked-copyDownload the checked copy: the student's PDF with ticks, crosses, notes and marks.
PATCH/submissions/{id}/questions/{qid}A teacher's override: marks (0.5 steps) and feedback for one question. Overrides are free.
POST/exams/{id}/finalizePublish draft marks as final, for chosen submissions or every graded one. Nothing is final until you call it.
POST/credits/quoteQuote the fixed price before you submit, and check your balance covers it.

Submission statuses

  • queuedWaiting for a grading slot, with queue position and estimated ready time.
  • processingGrading has started.
  • readingThe handwriting is being read.
  • gradingAnswers are being marked.
  • gradedEvery question was graded. Marks are drafts until you finalize.
  • partially_gradedAt least one question could not be graded; a teacher marks it.
  • failedThe copy could not be graded, e.g. unreadable. Reason in error.code. Not charged.
  • cancelledYou cancelled it. Not charged.

Not in the API yet

Planned, without dates. The docs' roadmap says what to do today for each.

  • Webhooks: poll the submission feed for now
  • Phone photos: send one PDF per answer sheet
  • Bulk scans split and matched by name: one PDF per candidate
  • Exams from a question-paper PDF: send questions as JSON
  • CSV results and Hindi or regional-language answers
API roadmap

Ready to build?

Read the docs, then ask us to switch the Evaluation API on for your institute. Tell us what you are building and your expected monthly volume.

Frequently asked questions

How do I get an API key?+

The Evaluation API is switched on per institute. Write to [email protected] (or use the demo page) to get it enabled. An institute admin then creates keys in the Vacademy dashboard under Settings → Integrations → API keys, with only the scopes each system needs.

Is there a sandbox?+

No. Every key is live and every graded copy is billed. Try things with a small exam of one or two short copies; failed and cancelled copies cost nothing.

Are there webhooks?+

Not yet; they are on the roadmap. Today you poll GET /submissions?updated_since= with a single worker, which the docs walk through step by step.

What can I upload?+

PDFs only, one per answer sheet, up to 50 MB each. Copies up to 40 pages are graded normally; 41 to 80 pages are graded and flagged for review; longer ones are refused before any charge. Phone photos must be combined into a PDF first.

How is it priced?+

1 credit per page of a handwritten PDF, blank pages included, and 1 credit per non-blank typed long answer. Objective answers are free. The price is fixed and quoted before grading; failed and cancelled copies are not charged; re-evaluating is charged again.

Do teachers have to use my app to review?+

No. Exams you create through the API also appear in the institute's Vacademy dashboard, tagged Source: API, where teachers can review and change marks. Their changes show up in your API results.

Which languages are supported?+

English answers only for now. Copies in Hindi or another regional language fail with language_not_supported and are not charged.

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.