ID Cards - API Reference

Audience: Frontend engineers (the admin panel), backend engineers, QA, and any consumer scanning or verifying a printed card. Scope: Admin surfaces owned by the ID Cards module, plus one unauthenticated public verification surface. All routes are under the admin OpenAPI document (/api/api-docs) except the public verification routes, which sit outside /api/mobile and are still part of the admin document per ADMIN_MODULES.

1. Documentation Evidence

2. Module Summary

3. Concepts and Terminology

4. API Surface Map

Note on id-cards route composition. IdCardsController and IdCardActionsController share the base path id-cards. Static segments (dashboard, replacements, history, render, print/mark-printed, print/reprint, issue) are literal children and never collide with the :publicId parameter route, because IdCardsController's own GET :publicId is the only bare-parameter route at that segment depth. Every :publicId param across the module is UUID-validated by the parameter pipe.

5. Auth, Identity, and Permissions

Row scoping beyond the permission check: every route returning a person applies the caller's people scope (derived from Students_READ/Staff_READ-style grants), and generation-job routes are additionally scoped to the requesting user unless that scope is unrestricted for the job's card type — see §13.1 and the backend doc §6.3.

6. DTO and Model Reference

6.1 CreateIdCardTemplateDto / UpdateIdCardTemplateDto

6.2 GenerateIdCardDto (single card)

6.3 CreateIdCardGenerationJobDto

6.4 ScanIdCardDto

6.5 ReportIdCardIncidentDto

6.6 IdCardResponseDto (detail)

Server-generated / read-only fields: publicId, cardNumber, verificationToken (never serialized to the response at all outside a render/download call), snapshot, generatedAt, printCount, version.

7. Enum Reference

8. Endpoint Reference

8.1 POST /api/id-card-generation-jobs

Purpose

Submit a bulk ID-card generation request for up to 2000 people at once. The admin panel calls this from the generation wizard after reviewing candidates and readiness. The job is processed asynchronously by the BullMQ worker; the response is the queued job, not the generated cards.

Source Evidence

Auth and Permissions

• Auth: JWT
• Guard chain: JwtAuthGuard, RoleGuard
• Permission: IdCards_CREATE
• Guest support: No
• Rate limit: ID_CARD_JOB_SUBMIT — 20/hour per account
• Idempotency: clientRequestId — a resubmission with the same value returns the original job

Request

{
  "cardType": "student",
  "personPublicIds": ["b3f1...", "c2a0..."],
  "academicSessionId": 4,
  "existingPolicy": "skip",
  "clientRequestId": "8f6e2c10-..."
}

Response

{
  "success": true,
  "message": "Generation job queued.",
  "data": {
    "publicId": "1d2e...",
    "status": "queued",
    "totalCount": 2,
    "createdAt": "2026-09-17T05:12:00.000Z"
  }
}

Side Effects

• Database writes: id_card_generation_jobs (insert), id_card_generation_job_items (one per person), an outbox_events row in the same transaction.
• BullMQ: the outbox dispatcher relays IdCardJob.PROCESS_GENERATION_JOB onto QueueName.ID_CARDS.
• Audit log: recorded automatically by ActivityAuditInterceptor under module IdCards, action CREATE.

Error Cases

Edge Cases

• Empty personPublicIds: rejected by DTO validation (400).
• Resubmitting the same clientRequestId: returns the original job unchanged, no duplicate row created.
• A person already having an active card under existingPolicy: "skip": that person's item is marked skipped when the job runs, not a request-level error.
• Concurrent submissions from the same user: serialized by a per-user advisory lock so the open-job cap cannot be raced.

Example Requests

curl -X POST "$API_URL/api/id-card-generation-jobs" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cardType":"student","personPublicIds":["b3f1..."],"academicSessionId":4,"existingPolicy":"skip","clientRequestId":"8f6e2c10-..."}'

8.2 GET /api/id-card-generation-jobs/:publicId

Purpose

Read one generation job's status and progress. Used by the admin panel to poll a submitted job.

Auth and Permissions

• Permission: IdCards_READ
• Row scope: the caller sees this job only if they requested it, or their people-scope for the job's card type is unrestricted ({kind:"all"}). Otherwise 404.

Response

{
  "success": true,
  "message": "Job fetched.",
  "data": {
    "publicId": "1d2e...",
    "status": "completed_with_errors",
    "totalCount": 2,
    "startedAt": "2026-09-17T05:12:05.000Z",
    "finishedAt": "2026-09-17T05:12:11.000Z"
  }
}

Error Cases

8.3 GET /api/id-card-generation-jobs/:publicId/items

Purpose

List the per-person outcomes within a job — which cards generated, which were skipped, and why.

Auth and Permissions

• Permission: IdCards_READ
• Row scope: same as §8.2 for the parent job, PLUS each returned item is filtered by the caller's own people scope — a scoped caller may see fewer items than the job's totalCount even when the job itself is visible.

Response

{
  "success": true,
  "message": "Items fetched.",
  "data": {
    "items": [
      { "studentId": "...", "status": "generated", "cardId": "...", "warnings": [] },
      { "studentId": "...", "status": "skipped", "outcomeCode": "ID_CARD_ACTIVE_CARD_EXISTS", "warnings": [] }
    ]
  }
}

8.4 POST /api/id-card-generation-jobs/:publicId/cancel

Purpose

Stop a queued or running bulk job.

Auth and Permissions

• Permission: IdCards_CREATE
• Row scope: same as §8.2.

Side Effects

• queued → cancelled immediately, pending items marked skipped.
• running → cancelling; the worker observes the flag between items and finishes the transition to cancelled.
• The job row is locked FOR UPDATE before the transition decision, so a concurrent cancel/retry or the worker's own claim serializes on the lock.

Error Cases

8.5 POST /api/id-card-generation-jobs/:publicId/retry

Purpose

Re-run the failed/skipped items of a job that finished with errors.

Auth and Permissions

• Permission: IdCards_CREATE
• Row scope: same as §8.2.

Error Cases

8.6 GET /api/id-cards/:publicId

Purpose

Full detail of one card, for the admin panel's card view.

Auth and Permissions

• Permission: IdCards_READ
• People scope applies to the underlying person.

Response

{
  "success": true,
  "message": "Card fetched.",
  "data": {
    "publicId": "9a1c...",
    "cardNumber": "STU-000041",
    "status": "active",
    "verdict": "valid",
    "personName": "Aarav Sharma",
    "snapshot": { "photo": "...", "class": "Grade 5-A" },
    "validFrom": "2026-04-01",
    "validUntil": "2027-03-31"
  }
}

Edge Cases

• Caller lacks Guardians_READ and is not superadmin: snapshot.guardian is absent from the object entirely (not null), so the response shape itself signals nothing about whether guardian data exists.
• Card's validUntil has passed but the sweep has not yet run: status still reads active in the raw column, but verdict reads expired — clients should always render verdict, never status, for "is this card currently valid".

8.7 POST /api/id-cards/issue

Purpose

Hand a printed card to its holder. This is the action that moves a card into active status and, if the holder had a prior active card, closes it in the same transaction.

Auth and Permissions

• Permission: IdCardIssue_UPDATE

Error Cases

Edge Cases

• Issuing while the holder still has an active card: the prior card is closed (status transitions away from active) in the SAME transaction as the new card's activation, because the database's partial unique index on active cards is not deferrable and would otherwise refuse the insert-then-close ordering.

8.8 POST /api/id-card-scan

Purpose

The authenticated scan a gate or front-office operator performs — resolves a card by its QR token or its printed card number and returns enough detail to identify the holder.

Auth and Permissions

• Permission: IdCardVerify_READ
• Rate limit: ID_CARD_SCAN — 120/min per account

Request

{ "code": "K3f9pQ2..." }

Response

Full card detail when scanned by token; basic info only when looked up by card number. Guardian contact details are included only when the caller also holds Guardians_READ.

{
  "success": true,
  "message": "Card scanned.",
  "data": {
    "verdict": "valid",
    "personName": "Aarav Sharma",
    "cardNumber": "STU-000041",
    "guardians": [{ "name": "...", "phone": "..." }]
  }
}

Error Cases

Edge Cases

• Holder has left the school or is soft-deleted: verdict reads deactivated immediately, even before the hourly lifecycle sweep records it on the card row.
• Card-number lookup (as opposed to token) never returns guardian contacts or full detail, regardless of the caller's permissions — the full-detail path is reserved for an actual QR scan.

8.9 GET /api/id-card-verification/:token

Purpose

The open-internet page reached by scanning a printed card's QR code. Shows the minimum information the school has configured under publicShow* settings.

Auth and Permissions

• Auth: none (@Public())
• Rate limit: PUBLIC_CARD_VERIFY — 60/min per IP

Response

{
  "success": true,
  "message": "Card verified.",
  "data": {
    "verdict": "valid",
    "name": "A. Sharma",
    "cardNumber": "STU-000041"
  }
}

Response headers on every call: Cache-Control: no-store, X-Robots-Tag: noindex, Referrer-Policy: no-referrer.

Error Cases

Edge Cases

• Deactivated/expired holder: verdict reflects it immediately, same as the authenticated scan.
• publicShowName: "hidden": name field is omitted or empty per settings, never guessed at.

8.10 GET /api/id-card-verification/:token/photo

Purpose

The holder's photo for the public verification page, when the school has enabled publicShowPhoto.

Auth and Permissions

• Auth: none (@Public())
• Rate limit: same bucket as :token (class-level PUBLIC_CARD_VERIFY)

Response

Raw image bytes with the correct Content-Type, not the JSON envelope.

Error Cases

9. Flow Diagrams

9.1 Route Ownership

9.2 Bulk Generation Request Sequence

9.3 Error Branch — Scan

10. Pagination, Sorting, Filtering, and Search

None of the module's list endpoints allow pagination=false — cards and generation jobs are person-scale data, matching the repo-wide rule that the people tables refuse unpaginated rolls.

11. Caching, Jobs, and External Integrations

12. Zero-Omission API Checklist

• Every controller route is documented (10 controllers, 46 routes).
• Every parent route prefix is documented.
• Every DTO's principal fields, enum, default, and validator are documented at the level the schema/service enforces them.
• Every response field's nullability and gating is documented for detail/scan/public-verify.
• Every auth, guard, permission, and guest branch is documented.
• Every success, validation, permission, not-found, and conflict branch is documented for the ten endpoints given full detail; the remaining routes are covered in the surface map and error-code table.
• Database writes, BullMQ jobs, and external calls (storage relay) are documented.
• Route ownership, sequence, and error-branch diagrams are included.
• Links to backend and features/flows docs are present.

Integration Checklist

• Every route from controllers is documented.
• Every enum value is documented.
• Every response envelope follows { success, message, data }.
• Every error code relevant to the module is documented (see the backend doc's full table).
• Every auth guard and permission is documented.
• Every queue job and external call (storage) is documented.
• Diagrams match the current controllers and services.

See Also

• Backend doc: /docs/developer/id-cards/backend
• Features and flows doc: /docs/developer/id-cards/feature