OneMarkGuru integration documentation

Getting Started

Register and approve a source system, securely receive its key ID and request secret, synchronize an immutable exam snapshot and candidates, then issue short-lived launch authorizations to authenticated candidates. Results are delivered by signed webhook and remain available through reconciliation.

Examples use fictional IDs and secrets. Never place production credentials in browser code, URLs, documentation, support messages, or logs.

Base URL

https://exam.onemarkguru.in/api/v1

Send UTF-8 JSON with Content-Type: application/json. Store every returned OneMarkGuru public ID with its source public ID.

Architecture

The source sends a complete exam snapshot over HTTPS. OneMarkGuru stores it independently and never queries the source database during an active exam. Candidates launch from an authenticated source session. OneMarkGuru commits the authoritative attempt and evaluation before delivery.

Source authoring → immutable synchronization → candidate launch → execution
Source reports ← signed result webhook ← authoritative evaluation

PostgreSQL holds authoritative state. Redis is limited to queues, cache, throttles, and ephemeral coordination; restarting Redis cannot erase answers or results.

Authentication

Every source API request uses HMAC-SHA256 v1.

Canonical request

OMG-HMAC-SHA256-V1
{unix_timestamp}
{nonce}
{UPPERCASE_METHOD}
{/api/v1/path?query}
{sha256_hex_of_exact_request_body}

Sign the exact transmitted bytes. Requests outside the clock window or using a prior nonce are rejected.

Source Systems

A source system is an approved college ERP, placement product, learning platform, or partner. Operations administrators control its status, capabilities, origins, optional IP allowlist, webhook destination, request credentials, and a separate webhook signing secret. Credentials may overlap during rotation and be revoked independently.

A disabled source or revoked/expired credential cannot synchronize, launch, acknowledge, or retrieve results.

Exams

PUT /exams/{externalExamId}/snapshots/{version} synchronizes one complete immutable version: organization snapshot, title/instructions, IANA timezone, UTC-aware boundaries, duration, marks, settings, sections, and questions.

Uniqueness is source + external exam ID + version. An identical retry returns the original response. Different normalized content at the same version is rejected; publish a higher version.

{"organization":{"external_id":"01ORGEXAMPLE","display_name":"Example College"},"title":"Placement Main Examination","timezone":"Asia/Kolkata","starts_at":"2026-09-10T04:30:00Z","ends_at":"2026-09-10T06:30:00Z","duration_minutes":90,"total_marks":100,"pass_marks":40,"sections":[],"questions":[]}

Sections

Sections are optional and use stable external IDs. They carry title, position, marks, optional duration, navigation policy, and metadata. Mixed exams place objective and programming questions in one attempt.

Candidates

PUT /exams/{externalExamId}/candidates/{externalCandidateId} upserts a display snapshot and assignment. Send snapshot version, stable assignment and organization IDs, display name, register identifier, and maximum attempts.

Never identify candidates using names, email alone, DOB, array position, or sequential database IDs. A retake creates a new attempt; it never reopens a submitted attempt.

Questions and snapshots

Common fields are stable external ID, type, prompt, context/media, marks, negative marks, position, section, metadata, and snapshot version. V1 types are single_choice, multiple_choice, true_false, and programming. Correct answers and hidden tests never appear in candidate resources.

MCQ

Each option has a stable external ID, content, position, and media. Send correct IDs only to the authenticated snapshot endpoint. V1 exact_set scoring requires the selected option set to exactly equal the correct set. Unanswered scores zero; incorrect applies configured negative marks. Partial scoring is not implied.

Programming

Snapshots include problem and I/O formats, constraints, samples, hint, supported/default languages, starter code, input mode, time/memory limits, comparator, visible tests, and hidden tests.

Run Code

Run executes saved source with custom input only and returns safe status, stdout, sanitized diagnostics, and timing. It never runs assessment tests.

Check All Tests

Check evaluates visible and hidden tests against the exact source digest. Visible results may show input, expected, actual, safe error, and pass/fail. Hidden results contain only label and pass/fail. Editing source causes Recheck Required.

Default score is passed tests ÷ total tests × question marks. thaailearn_compatible normalizes line endings, trailing horizontal whitespace, surrounding blank lines, and final newline; exact and whitespace_tolerant are explicit alternatives.

Candidate Launch

POST /exams/{externalExamId}/candidates/{externalCandidateId}/launch-authorizations returns a URL valid for 30–900 seconds. Its token is exam/candidate specific, random, stored hashed, and consumed once.

Create it only after authenticating the student. OneMarkGuru creates or resumes the assigned attempt and binds one active session. Another device/tab replaces the prior session and produces an audit event.

Lifecycle

OneMarkGuru controls start eligibility, timer, expiry, submission, and lock. Browser time is display-only. Candidate screens poll server state so upcoming becomes startable and expiry becomes completed without refresh.

Scheduled reconciliation evaluates the latest persisted answers and locks exactly once even when disconnected. Submitted, auto-submitted, cancelled, expired, and administratively locked attempts reject all mutations.

Results

The result includes schema version, source references, OneMarkGuru IDs, timestamps, submission reason, marks, percentage, optional pass result, and per-question data. Programming includes final language/source, score, passed/total tests, safe summary, and aggregate timing. Hidden values and judge internals are excluded.

GET /attempts/{attemptPublicId}/result retrieves the authoritative payload and digest used for delivery.

Webhooks

OneMarkGuru posts attempt.result_ready after committing the result. Verify X-OMG-Webhook-Timestamp, X-OMG-Webhook-Delivery, and X-OMG-Webhook-Signature using the distinct webhook secret.

OMG-WEBHOOK-SHA256-V1
{unix_timestamp}
{delivery_public_id}
{sha256_hex_of_exact_body}

Use constant-time comparison, reject stale timestamps, deduplicate by delivery ID, persist before returning 2xx, then POST /result-deliveries/{deliveryId}/acknowledge with payload_digest.

Reconciliation

Failed callbacks remain in a PostgreSQL outbox and retry with bounded exponential backoff. Pull by attempt ID and acknowledge by delivery ID. Duplicate callbacks are normal and must not create duplicate source attempts, answers, submissions, or reports.

Errors

{"error":{"code":"idempotency_conflict","message":"This idempotency key was used for a different request.","details":{}},"meta":{"request_id":"01REQUESTEXAMPLE"}}

Rate Limits

Limits vary by capability and endpoint. Respect 429 and Retry-After, use exponential backoff with jitter, and retry identical mutations with the same idempotency key. Run/Check is restricted per attempt and IP.

Security recommendations

• Keep request and webhook secrets separate in a managed secret store.
• Verify TLS and synchronize UTC clocks.
• Generate nonce and idempotency keys cryptographically.
• Never log secrets, correct answers, hidden tests, or candidate source code.
• Verify webhook timestamp/signature before parsing or mutation.
• Rotate credentials and use allowlists where practical.
• Launch only after source authentication; never use DOB as a password.

Versioning

The major API version is in the URL. Additive fields may appear within v1 and clients must ignore unknown fields. Breaking authentication, field, lifecycle, or semantic changes use a new major version and migration window. Results carry an independent schema_version.

Example integration

1. Create the exam in the existing authoring workflow.
2. Freeze source public IDs and synchronize snapshot v1.
3. Synchronize assigned candidates.
4. At Start Exam, request and redirect to a one-time launch URL.
5. Verify, persist, and deduplicate the result webhook.
6. Map it into existing report tables and acknowledge its digest.
7. Periodically reconcile unacknowledged attempts.

For onboarding, contact onemarkguru@gmail.com.