# qb-cityhall: license issuance and job applications

`qb-cityhall` provides a city-hall interface for identity documents, driving and weapon licenses, and public job applications. The current reference is pinned to [commit 020f041](https://github.com/qbcore-fivem/qb-cityhall/tree/020f041465c6b6fcdb7421e6bf1b82ab92b22d19). It does **not** provide the police-side authorization to grant a weapon license.

## Installation and dependencies

Start `qb-core`, `qb-inventory` and the relevant interaction/resource dependencies before `qb-cityhall`. The bundled [`client.lua`](https://github.com/qbcore-fivem/qb-cityhall/blob/020f041465c6b6fcdb7421e6bf1b82ab92b22d19/client.lua) opens menus and handles NPC interaction, while [`server.lua`](https://github.com/qbcore-fivem/qb-cityhall/blob/020f041465c6b6fcdb7421e6bf1b82ab92b22d19/server.lua) handles job and item operations.

- `Config.UseTarget` follows the `UseTarget` server convar.
- `Config.AvailableJobs` lists publicly available jobs such as `taxi`, `trucker` and `bus` when not using `qb-jobs`.
- `Config.Cityhalls` lists hall positions and purchasable `licenses`.
- `Config.DrivingSchools` configures instructor IDs and driving-school positions.
- `Config.Peds` configures NPC models, positions and interaction zones.

## License configuration

The [upstream config](https://github.com/qbcore-fivem/qb-cityhall/blob/020f041465c6b6fcdb7421e6bf1b82ab92b22d19/config.lua) includes these document keys:

| Item key | Default cost | Eligibility |
| --- | --- | --- |
| `id_card` | `50` | Public |
| `driver_license` | `50` | Player metadata `licences.driver` |
| `weaponlicense` | `50` | Player metadata `licences.weapon` |

The upstream item is named `weaponlicense`, while the eligibility metadata uses `weapon`. Buying a hard-copy document is different from receiving the underlying permission. For the end-to-end flow, use the [weapon-license guide](/docs/guides/weapon-license).

## Integration surface

The server exports `AddCityJob(jobName, toCH)`. A job object requires `label` and `isManaged` and the export returns success/status. This changes the resource's runtime job list; it does not automatically create a QBCore shared job definition.

~~~lua filename="server.lua"
-- Only after the 'delivery' job exists in qb-core and your server has
-- configured its grades, payroll and permissions:
local ok, reason = exports['qb-cityhall']:AddCityJob('delivery', {
    label = 'Delivery Driver',
    isManaged = false,
})
print(ok, reason)
~~~

Bundled QBCore callbacks: `qb-cityhall:server:receiveJobs` and `qb-cityhall:server:getIdentityData`.

Server network events: `qb-cityhall:server:requestId`, `qb-cityhall:server:sendDriverTest`, `qb-cityhall:server:ApplyJob` and `qb-cityhall:server:getIDs`. The `getIDs` event invokes the bundled starter-item issuance handler; it is not registered with `CreateCallback`.

These are internal menu operations, not permission-granting public APIs. In the reviewed implementation, `requestId` indexes a client-supplied hall/license entry without a complete independent eligibility check. Validate any externally exposed purchase flow server-side before depending on it for restricted documents.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| Weapon/driver license not offered | Metadata `licences` and the selected hall's configured `licenses` |
| Document cannot be purchased | Cash balance, exact item name in shared items and `qb-inventory` |
| City job missing | `Config.AvailableJobs`, `qb-jobs` integration and availability callback |
| NPC/menu not visible | `UseTarget` convar, `Config.Peds` zones and resource startup |
| Item has incorrect personal data | `charinfo` on the loaded QBCore player and document item metadata |

## Update checklist

1. Compare installed city-hall code with the pinned upstream configuration and server handlers.
2. Test license visibility **with and without** player eligibility.
3. Test ID issuance and job application from an allowed and an unauthorized character.
4. Do not add new purchase/permission events without server-side authorization checks.

## Sources

[Repository](https://github.com/qbcore-fivem/qb-cityhall/tree/020f041465c6b6fcdb7421e6bf1b82ab92b22d19) · [Config](https://github.com/qbcore-fivem/qb-cityhall/blob/020f041465c6b6fcdb7421e6bf1b82ab92b22d19/config.lua) · [Server exports/events](https://github.com/qbcore-fivem/qb-cityhall/blob/020f041465c6b6fcdb7421e6bf1b82ab92b22d19/server.lua)
