> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aps-store.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Document Office

Players order documents with a validity period. Expired documents are shown as such.

```lua theme={null}
{
    id          = 'badge',
    name        = 'Badge',
    description = 'Official law enforcement badge.',
    icon        = 'BadgeCheck',   -- Car, Shield, CreditCard, BadgeCheck, Scale, HeartPulse, FileText
    allowedJobs = { 'police', 'sheriff' },   -- optional, nil = everyone
    minGrade    = 2,                         -- optional
    options     = {
        { label = '30 Days', days = 30,  price = 0 },
        { label = '1 Year',  days = 365, price = 0 },
    },
},
```

Restricted documents are shown greyed out with the required job underneath. Add `item = 'id_card'` to give an inventory item on order (see [Compatibility](https://docs.aps-store.com/assets/aps_cityhall/compability.md)). After ordering, `Config.OnDocumentOrdered` runs.

## Document items

Every document type with an `item` becomes a real document: a serial number, the holder's webcam photo, a signature and the fields you list. No extra script is needed.

```lua theme={null}
-- config/documents.lua
Config.DocumentSystem = {
    system       = 'auto',   -- 'auto' | 'builtin' | 'vms_documentsv2'
    showDistance = 3.0,
    showSeconds  = 10,
    reprintPrice = 50,       -- My documents → Print copy
    checkCommand = { enabled = true, name = 'checkdocument', jobs = { police = 0, sheriff = 0, government = 0 } },
}

{
    id       = 'id_card',
    name     = 'ID Card',
    item     = 'id_card',     -- given on order
    prefix   = 'ID-',         -- serial → ID-482913
    template = 'card',        -- 'card' | 'badge'
    fields   = { 'firstName', 'lastName', 'dateOfBirth', 'sex', 'height', 'nationality', 'ssn' },
    vms      = 'id_card',     -- name in vms_documentsv2
    options  = { … },
},
```

* **Fields:** `firstName`, `lastName`, `dateOfBirth`, `sex`, `height`, `nationality`, `ssn`, `job`, `jobGrade`. The data is saved when the document is issued (like a printed card). Fields the framework doesn't have are left out.
* **SSN:** ESX's own `users.ssn` is used; on other frameworks City Hall gives every character a unique SSN (`aps_citizens`).
* **Using the item** shows the document to the holder and everyone within `showDistance` as an ID-1 card in US driver-license layout (field codes, ghost photo, printed skyline), with a live *VALID* hologram or *EXPIRED / REVOKED* stamp. H (`flipKey`) turns it over to the back side (barcodes, restrictions, issuer) and back; Backspace (`hideKey`) puts it away early. `template = 'badge'` uses a dark badge-case layout.
* **/checkdocument** lets the listed jobs (job = minimum grade) look up any document.
* **Lost items:** *My documents → Print copy* prints the same document again for `reprintPrice`. Revoking a document in the Government Portal invalidates every copy.
* **Items:** ESX inventory — `sql/items_esx.sql`. ox\_inventory — add `server = { export = 'aps_cityhall.useDocument' }` and `consume = 0` to each document item (see [License cards → Items](https://docs.aps-store.com/assets/aps_cityhall/guides/document-cards-and-webcam.md) for the format).

## vms\_documentsv2

* With `system = 'auto'` and vms\_documentsv2 running (start it before `aps_cityhall`), the Document Office issues documents through vms\_documentsv2 using each type's `vms` name, including the license documents (Driving → `driving_license`, Boat → `boat_license`, Pilot → `flying_license`, CCW → `weapon_license`). Revoking in the Government Portal calls vms' `invalidateDocument`.
* The default item names match vms\_documentsv2's (`id_card`, `driving_license`, `police_badge`, `weapons_license`), so switching systems doesn't need new items.
* Without vms\_documentsv2, `Config.Compat.vmsDocuments = true` answers scripts that call `exports['vms_documentsv2']`: `giveDocument`, `isAnyDocumentValid`, `invalidateDocument`, `getMyDocuments`, `GenerateSSN`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.