Dociya

Wallet cards

WalletCard isn't its own resource — it's the shape every document comes back in from GET /documents and GET /documents/:id (which extends it with fields and version history). This page documents that shape once instead of repeating it.

Example

{
  "id": "5b1e2b7a-...",
  "title": "Driver's License",
  "docType": "us_dl",
  "category": "identity",
  "status": "active",
  "maskedNumber": "DL ••••4562",
  "cardholder": "Priya Sharma",
  "starred": false,
  "tags": [],
  "ingestionStatus": "done",
  "nextDeadlineAt": "2028-04-12",
  "issuer": "California DMV",
  "issuerKey": "ca-dmv",
  "logoUrl": null,
  "inWallet": true,
  "provenance": "user-uploaded",
  "card": {
    "template": "dl",
    "category": "identity",
    "motif": "shield",
    "kicker": "DRIVER'S LICENSE",
    "title": "Driver's License",
    "number": { "value": "DL ••••4562", "state": "ok" },
    "facts": [
      { "label": "CLASS", "value": "C" },
      { "label": "EXPIRES", "value": "2028-04-12" },
      { "label": "STATE", "value": "CA" }
    ]
  }
}

Two layers

WalletCard carries two things at once: flat fields for filtering/sorting (status, category, starred, nextDeadlineAt…), and a nested card object — the full, registry-bound face every surface in the app renders identically (wallet stack, list row, detail hero, chat card). One definition, every surface.

Top-level fields worth knowing
maskedNumberstring | nulloptional

Pre-masked primary identifier (••••last4). Never the full value — see the reveal endpoint.

issuerstring | nulloptional

The issuing organization, derived server-side from public extracted fields. Never guessed — null when the document names no issuer.

issuerKeystring | nulloptional

Normalized brand-lookup slug for issuer (e.g. "ca-dmv", "blue-shield"). Clients use this to render a designed lockup.

logoUrlstring | nulloptional

A verified real-world logo for issuerKey, resolved live at read time — see Brand logos. null until an issuer's logo passes review; clients fall back to a monogram, never a broken image. Presigned & short-TTL — don't cache past one screen load.

ingestionStatusstring | nulloptional

"done" | "review" | "processing" | "queued" | "failed" | null — lets a feed show only finished cards while the full list shows everything.

provenance"user-uploaded" | "digilocker-issued"optional

A DigiLocker-synced document is stamped issued rather than uploaded — see DigiLocker.

inWalletbooleanoptional

Curated-wallet membership. The Library is the complete collection; the wallet is a subset. Absent on the wire is treated as true.

The card face

CardPresentation
templateCardTemplateIdoptional

Which chassis to render — one of a fixed registry (dl, passport, insurance, generic, …).

kickerstringoptional

Localized micro-label, e.g. "DRIVER'S LICENSE".

titlestringoptional

The ladder title — never the literal word "document", never a bare placeholder.

number{ value: string | null, state: "ok" | "review" }optional

The mono number line. state: "review" means the number is expected but not yet confirmed — clients render "tap to review & confirm".

factsCardFact[]optional

Up to 5 ordered facts. A fact with value: null renders as an em-dash, never omitted or invented.

Note
Fields marked optional on the wire (issuer, issuerKey, logoUrl, card, inWallet, provenance) exist so older clients keep decoding as this shape grows — treat their absence the same as null / the documented default, not as an error.