Paper checking,
one API away.
Send a student answer sheet and a complete model-answer PDF. TickAutoAI extracts the rubric, grades the answers, and returns structured JSON for your own application.
https://service.tickautoai.comUse this API from your server. All examples below use organisation API keys.
01 / Your first evaluation
- Create an organisation and sign in.
- Top up credits from the console using Razorpay.
- Create an API key and save it in your server’s secret store.
- Upload both PDFs, save the returned job ID, then poll for results.
curl https://service.tickautoai.com/api/v1/evaluations \ -H "Authorization: Bearer $TICKAUTOAI_API_KEY" \ -H "Idempotency-Key: exam-2026-student-042" \ -F "student_pdf=@student.pdf" \ -F "model_answer_pdf=@model-answer.pdf" \ -F "student_name=Aarav" \ -F "external_id=your-submission-042" \ -F "checking_mode=NORMAL"
You receive 202 Accepted with a job ID and status_url. Evaluation continues even if you close the connection.
Authentication
Authorization: Bearer ta_live_…
Keys belong to one organisation. They can submit evaluations, read that organisation’s evaluations, and read the available balance. Keys cannot buy credits or manage other keys. Create and revoke keys in the console. The full secret is displayed only once; rotate a key by creating a replacement and revoking the old one.
What your PDFs must contain
Student PDF
A legible scan of the student’s handwritten or typed answers. Keep full question labels visible, use the same labels as the model answer, and include every page in the correct order.
Model-answer PDF
Each question needs its full label, question text, reference answer, and explicit maximum marks. Include marking points where available. Label subquestions uniquely, such as Q2(a)(i).
- Each file: up to 20 MiB and 100 pages. Password-protected or invalid PDFs fail validation.
- V1 supports mandatory-question descriptive papers, including mathematical text and diagrams through the existing grader.
- Pure MCQ/OMR keys and optional-question rules such as “attempt any 3” are not supported by this two-PDF adapter yet.
- A bare answer key without question stems or marks is insufficient. Missing or ambiguous rubric information causes a failed job and refund.
- Extraction and grading can need human review. Use the returned review flags rather than assuming every scan was read perfectly.
Create an evaluation
Content type: multipart/form-data. Let your HTTP library set the boundary.
| Field | Required | Description |
|---|---|---|
| student_pdf | Yes | Student answer sheet PDF |
| model_answer_pdf | Yes | Complete marking-scheme PDF |
| student_name | No | Display name; defaults to Student (150 characters max) |
| external_id | No | Your own reference (150 characters max) |
| checking_mode | No | NORMAL (default) or STRICT |
Send an Idempotency-Key header of 8–128 characters (letters, numbers, underscore, period, colon, or hyphen). Reuse the same key and identical inputs after a network timeout. Replays return the original job, including its terminal status, without a second reservation or evaluation. Different inputs with the same key return 409. Use a new key for an intentional new evaluation.
Poll for completion
curl https://service.tickautoai.com/api/v1/evaluations/JOB_ID \ -H "Authorization: Bearer $TICKAUTOAI_API_KEY"
Poll every 5 seconds. Status progresses from queued to processing, then completed or failed. A successful HTTP response does not imply the evaluation itself succeeded—inspect status. Before completion, result and charged_paise are null.
On HTTP 429 or 5xx, back off and retry. A local timeout does not cancel the job. Save the ID and resume polling later; never create another job just because polling timed out. Processing time depends on page count, scans, and worker load.
Lists up to 50 jobs. Follow next_cursor using before until null. Ordering is descending opaque job ID, not creation time.
Marks, feedback & annotations
Illustrative completed response (the price is an example, not a fixed quote):
{
"id": "b10242c1-6a18-40df-968c-cf21d9a7330e",
"status": "completed",
"external_id": "your-submission-042",
"student_name": "Aarav",
"checking_mode": "NORMAL",
"created_at": "2026-11-18T10:00:00.000Z",
"completed_at": "2026-11-18T10:01:20.000Z",
"billing": {
"currency": "INR",
"reserved_paise": 5000,
"charged_paise": 47
},
"result": {
"total_marks": 2,
"max_marks": 3,
"percentage": 66.67,
"questions": [
{
"question_number": 1,
"label": "Q1(a)",
"question_text": "State Newton’s second law.",
"student_answer": "Force is mass times acceleration.",
"marks_awarded": 2,
"max_marks": 3,
"feedback": {
"short": "Definition incomplete",
"detailed": "The relation is correct. Include the rate of change of momentum."
},
"confidence": 0.94,
"needs_review": false,
"review_reasons": []
}
],
"annotations": [
{
"question_label": "Q1(a)",
"page_index": 0,
"x": 0.12,
"y": 0.34,
"marks_awarded": 2,
"max_marks": 3,
"feedback": "Definition incomplete"
}
],
"annotation_status": "available",
"needs_review": false,
"annotation_coordinates": {
"origin": "top-left",
"units": "normalized",
"page_index_base": 0
}
},
"error": null,
"status_url": "/api/v1/evaluations/b10242c1-6a18-40df-968c-cf21d9a7330e"
}questions includes the extracted student answer, awarded marks, maximum marks, feedback, model confidence, and review reasons. needs_review signals unresolved answers or other grading uncertainty. Confidence is the grader’s score, not a calibrated probability.
Draw annotations on your PDF viewer
const left = annotation.x * renderedPageWidth; const top = annotation.y * renderedPageHeight; // page_index is ZERO-based. Coordinates originate at TOP LEFT. // Position a mark/feedback overlay at (left, top) on that page.
Annotation entries reference question labels and carry marks and a short comment. The original PDF remains yours; this API returns overlay data rather than an annotated PDF download. Respect the original page orientation and dimensions.
annotation_status is available, partial, or unavailable. A missing placement is not a zero score. Display the question-level results and offer review when placements are incomplete.
Prepaid credits
The response includes available_paise and evaluation_reserve_paise. ₹1 equals 100 paise and 1 credit. Buy ₹500–₹10,000 per top-up through the console.
- A reservation is deducted atomically when a new job is accepted. The initial default is ₹50 per job; use the balance endpoint for the current amount.
- On completion, the final metered usage charge is deducted from that reservation and the unused amount is released.
- The final charge cannot exceed the reservation returned for that job.
- Failed jobs are fully refunded. Replays of an Idempotency-Key do not incur an additional charge.
- While an upstream job is unreachable, the reservation remains held until its outcome can be reconciled.
The console shows available credits, final spend, and ledger entries for purchases, reservations, and releases.
Errors & limits
{
"error": {
"code": "insufficient_credits",
"message": "At least 5000 available paise are required.",
"request_id": "request-uuid"
}
}| HTTP status | Action |
|---|---|
| 400 | Check required fields, PDF format, and Idempotency-Key. |
| 401 | Check the key; revoked keys stop working immediately. |
| 402 | Top up credits, then retry with the same Idempotency-Key. |
| 404 | Check the job ID and organisation key. |
| 409 | Reuse the original inputs or choose a new Idempotency-Key. |
| 413 | Reduce file sizes; 20 MiB per PDF. |
| 429 | Wait before retrying; follow Retry-After. |
| 500 / 502 / 503 | Retry with backoff and the same Idempotency-Key. |
Limits: 120 API requests/minute per organisation, including polls; at most 20 new submission requests/minute. Limits apply across all keys for an organisation. Poll multiple jobs thoughtfully.
Terminal job error codes include INVALID_PDF, INVALID_MODEL_ANSWER, AMBIGUOUS_QUESTION_LABELS, and EVALUATION_FAILED. These appear inside a job response, not as an HTTP error. Correct the input and submit with a new key.
Server-side examples
Python · upload and poll
Install requests; set TICKAUTOAI_API_KEY in your environment.
import os, time, requests
base = "https://service.tickautoai.com"
headers = {"Authorization": "Bearer " + os.environ["TICKAUTOAI_API_KEY"]}
with open("student.pdf", "rb") as student, open("model-answer.pdf", "rb") as model:
response = requests.post(base + "/api/v1/evaluations",
headers={**headers, "Idempotency-Key": "exam-2026-student-042"},
files={"student_pdf": student, "model_answer_pdf": model},
data={"student_name": "Aarav"}, timeout=120)
response.raise_for_status()
job = response.json()
deadline = time.monotonic() + 1800
while job["status"] not in ("completed", "failed"):
if time.monotonic() > deadline:
raise TimeoutError("Keep job ID for later polling: " + job["id"])
time.sleep(5)
response = requests.get(base + job["status_url"], headers=headers, timeout=30)
if response.status_code == 429 or response.status_code >= 500:
time.sleep(30)
continue
response.raise_for_status()
job = response.json()
if job["status"] == "failed":
raise RuntimeError(job["error"])
print(job["result"]["total_marks"], job["result"]["max_marks"])
print(job["result"]["annotations"])Node.js 22+ · upload
import { readFile } from "node:fs/promises";
const base = "https://service.tickautoai.com";
const headers = { Authorization: "Bearer " + process.env.TICKAUTOAI_API_KEY };
const form = new FormData();
form.set("student_pdf", new Blob([await readFile("student.pdf")],
{ type: "application/pdf" }), "student.pdf");
form.set("model_answer_pdf", new Blob([await readFile("model-answer.pdf")],
{ type: "application/pdf" }), "model-answer.pdf");
const response = await fetch(base + "/api/v1/evaluations", {
method: "POST", headers: { ...headers, "Idempotency-Key": "exam-2026-student-042" },
body: form, signal: AbortSignal.timeout(120000)
});
if (!response.ok) throw new Error(await response.text());
const job = await response.json();
// Persist job.id. Poll job.status_url every 5 seconds until terminal.
console.log(job.id, job.status_url);Import the OpenAPI specification into your API client or SDK generator for the complete machine-readable contract.
Integration support
When contacting your TickAutoAI account contact, include your evaluation ID and the X-Request-Id response header. Do not include API keys. For job-level failures, include the error code and whether the reference PDF meets the rubric requirements.