> ## 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.

# Server Exports

`target` is always a player server id **or** an identifier (ESX `identifier` / QBCore & Qbox `citizenid`), so most exports also work for offline players.

> [!NOTE]
>
> Moving from vms\_cityhall? With `Config.Compat.vmsCityhall = true` the same calls work on `exports['vms_cityhall']`. See [Compability](https://docs.aps-store.com/assets/aps_cityhall/compability.md).

***

## General

### openCityHall

Opens the PC for a player anywhere on the map (laptop item, MDT…). That PC session skips the City Hall location check until the player closes it.

```lua theme={null}
---@param playerId number
---@return boolean success
exports['aps_cityhall']:openCityHall(playerId)
```

### giveBill

Sends a bill to a player. Uses the same data format as vms\_cityhall's `giveBill`; its argument order `(source, type, data, giveItem, cb)` is accepted too.

```lua theme={null}
---@param playerId number
---@param billType string: 'invoice' | 'ticket' | 'traffic-ticket' | 'receipt'
---@param billData table
---@param cb function|nil: called with billId (nil on failure)
exports['aps_cityhall']:giveBill(playerId, billType, billData, cb)
```

> [accordion] Explanation
>
> | Type | Amount from |
> | - | - |
> | `ticket`, `traffic-ticket` | `amount` |
> | `invoice` | sum of `invoiceData` rows `{ qty, unitPrice, description }` |
> | `receipt` | sum of `receiptData` rows `{ qty, unitPrice, item }` |
>
> #### Common fields
>
> * `issuerName` (string), `job` (string), `society` (string, optional), `jobLabel` (string, optional)
> * `dateToPay` (number): days until overdue, `-1` = no due date
> * `comments` (string, optional)
> * `taxFromInvoice` / `taxFromReceipt` (number, optional): percent added on top
> * `percentageForSociety` (number, optional): share paid to the society, default `Config.Society.defaultPercent`
>
> #### Traffic tickets
>
> * `violation`, `locationOfViolation`, `vehicle = { plate, model }`
> * `penaltyPointsCount` (number): adds [penalty points](https://docs.aps-store.com/assets/aps_cityhall/guides/suspension-and-penalty-points.md)
> * `license` + `licenseSuspensionTime` (seconds) or `licenseRevocation = true`
>
> #### Example:
>
> ```lua theme={null}
> exports['aps_cityhall']:giveBill(targetSource, 'traffic-ticket', {
>     issuerName          = 'Officer Smith',
>     job                 = 'police',
>     amount              = 750,
>     dateToPay           = 7,
>     violation           = 'Speeding (45 km/h over the limit)',
>     locationOfViolation = 'Great Ocean Hwy',
>     vehicle             = { plate = 'ABC 123', model = 'Sultan' },
>     penaltyPointsCount  = 4,
> }, function(billId)
>     print('bill created', billId)
> end)
> ```

***

## Licenses

### getLicenses

```lua theme={null}
---@return table: list of license ids, e.g. { 'car', 'boat' }
local list = exports['aps_cityhall']:getLicenses(target)
```

### hasLicense

Returns `false` while the license is suspended.

```lua theme={null}
---@param license string: id from config/licenses.lua
---@return boolean
local has = exports['aps_cityhall']:hasLicense(target, 'car')
```

### addLicense

```lua theme={null}
---@return boolean: false if already owned
local added = exports['aps_cityhall']:addLicense(target, 'car')
```

### removeLicense

Revokes a license (also in the synced framework license system).

```lua theme={null}
---@return boolean
local removed = exports['aps_cityhall']:removeLicense(target, 'car')
```

### suspendLicense

```lua theme={null}
---@param seconds number: 0 = until reinstated
---@param reason string
exports['aps_cityhall']:suspendLicense(target, 'car', 7 * 86400, 'Reckless driving')
```

### reinstateLicense

```lua theme={null}
exports['aps_cityhall']:reinstateLicense(target, 'car')
```

### isLicenseSuspended

Other scripts' license names (`drive_b`, `practical_boat`…) are translated with `Config.Compat.licenseAliases`.

```lua theme={null}
---@return boolean suspended, number|nil untilTime
local suspended, untilTime = exports['aps_cityhall']:isLicenseSuspended(target, 'car')
```

### getSuspendedLicenses

```lua theme={null}
---@return table: active suspensions keyed by license id
local list = exports['aps_cityhall']:getSuspendedLicenses(target)
```

### getPenaltyPoints / addPenaltyPoints / removePenaltyPoints / resetPenaltyPoints

```lua theme={null}
local points = exports['aps_cityhall']:getPenaltyPoints(target)
exports['aps_cityhall']:addPenaltyPoints(target, 4, 'Speeding')
exports['aps_cityhall']:removePenaltyPoints(target, 2, fromList)
exports['aps_cityhall']:resetPenaltyPoints(target)
```

***

## Documents

### hasDocument

```lua theme={null}
---@param docType string: id from config/documents.lua
---@return boolean valid, string|nil expiresAt
local valid, expiresAt = exports['aps_cityhall']:hasDocument(target, 'id_card')
```

### addDocument

Adds a document or extends a valid one.

```lua theme={null}
---@param days number
---@return string newExpiry
local newExpiry = exports['aps_cityhall']:addDocument(target, 'id_card', 30)
```

### issueDocument

Issues a document item for free (e.g. from a job script). `days` defaults to the longest validity option of the type.

```lua theme={null}
---@param source number
---@param docType string
---@param days number|nil
---@return string|nil serial
local serial = exports['aps_cityhall']:issueDocument(source, 'id_card')
```

### getDocumentBySerial

```lua theme={null}
---@return table|nil: { serial, type, name, holder, status, issued, expires, identifier }
local doc = exports['aps_cityhall']:getDocumentBySerial('ID-482913')
```

### isDocumentValid

```lua theme={null}
---@return boolean
local valid = exports['aps_cityhall']:isDocumentValid('ID-482913')
```

### getCitizenSSN

```lua theme={null}
---@return string|nil: e.g. '123-45-6789'
local ssn = exports['aps_cityhall']:getCitizenSSN(source)
```

### GenerateSSN

Returns a new unique SSN. Same signature as vms (`GenerateSSN(dob, sex)`), both arguments are ignored.

```lua theme={null}
local ssn = exports['aps_cityhall']:GenerateSSN()
```

***

## Insurance

### getHealthInsurance / addHealthInsurance

Uses the document type `Config.Compat.healthInsurance`.

```lua theme={null}
---@return boolean insured, number|nil expiresUnix
local insured, expiresUnix = exports['aps_cityhall']:getHealthInsurance(target)
exports['aps_cityhall']:addHealthInsurance(target, 7)   -- days
```

### getVehicleInsurance / addVehicleInsurance

Accepts a plate or a VIN. Adding extends a running policy.

```lua theme={null}
---@return boolean insured, string startDate, string expiryDate
local insured, startDate, expiryDate = exports['aps_cityhall']:getVehicleInsurance('ABC 123')
exports['aps_cityhall']:addVehicleInsurance(30, 'ABC 123')   -- days, plate
```

***

## Taxes & Treasury

### getTaxAmount

```lua theme={null}
---@return number total, number tax, number percent
local total, tax, percent = exports['aps_cityhall']:getTaxAmount(250, 'products.food')
```

### addPlayerTaxToPay

Adds a personal tax using a rate from `Config.Taxes`.

```lua theme={null}
---@param identifier string
---@param fromAmount number
---@param taxPath string
---@param title string
exports['aps_cityhall']:addPlayerTaxToPay(identifier, 25000, 'gains.vehicleexcise', 'Vehicle sale')
```

### addPlayerCustomTaxToPay

```lua theme={null}
exports['aps_cityhall']:addPlayerCustomTaxToPay(identifier, price, 15, 'Property purchase tax')   -- percent
```

### addPlayerFlatTax

```lua theme={null}
exports['aps_cityhall']:addPlayerFlatTax(identifier, 500, 'Parking permit', category)
```

### getPlayerTaxes

```lua theme={null}
local taxes = exports['aps_cityhall']:getPlayerTaxes(target)
```

### addCompanyTaxAmount / addCompanyCustomTaxAmount / addCompanyFlatTaxAmount

Business income is added to the current month's tax account.

```lua theme={null}
exports['aps_cityhall']:addCompanyTaxAmount('ltd1', 250, 'products.food')   -- rate from Config.Taxes
exports['aps_cityhall']:addCompanyCustomTaxAmount('taxi', total, 8)         -- percent
exports['aps_cityhall']:addCompanyFlatTaxAmount('mechanic', 500)            -- fixed tax
```

### registerBusinessTaxAccount

```lua theme={null}
exports['aps_cityhall']:registerBusinessTaxAccount('taxi', 'Downtown Cab Co')
```

> [!WARNING]
>
> Prefer `Config.BusinessTaxes.accounts` in [taxes.lua](https://docs.aps-store.com/assets/aps_cityhall/configuration-files/taxes.lua.md) for permanent accounts.

### getJobTaxes

```lua theme={null}
---@return table: { ['MM:YYYY'] = { amount, earned, total, status, … } }
local taxes = exports['aps_cityhall']:getJobTaxes('taxi')
```

### getTreasuryMoney / addTreasuryMoney / removeTreasuryMoney

```lua theme={null}
local balance = exports['aps_cityhall']:getTreasuryMoney()
exports['aps_cityhall']:addTreasuryMoney(5000)
exports['aps_cityhall']:removeTreasuryMoney(5000)
```

***

## Businesses

`business` is a business id or name.

### playerHasPermit

True when the player owns or works for an active business with a valid permit.

```lua theme={null}
---@return boolean ok, string|nil businessName
local ok, businessName = exports['aps_cityhall']:playerHasPermit(source, 'alcohol')
```

> [accordion] Example usage
>
> ```lua theme={null}
> if not exports['aps_cityhall']:playerHasPermit(source, 'alcohol') then
>     return TriggerClientEvent('ox_lib:notify', source, { type = 'error', description = 'You need an alcohol license.' })
> end
> ```

### hasBusinessPermit

```lua theme={null}
---@return boolean valid, string|nil expiresAt
local valid, expiresAt = exports['aps_cityhall']:hasBusinessPermit('Downtown Cab Co', 'transport')
```

### isBusinessEmployee

```lua theme={null}
---@return boolean, string|nil role: 'owner' | 'employee'
local isStaff, role = exports['aps_cityhall']:isBusinessEmployee(source, 12)
```

### isBusinessVehicle

```lua theme={null}
---@return boolean, number|nil businessId, string|nil businessName
local isBiz, id, name = exports['aps_cityhall']:isBusinessVehicle(GetVehicleNumberPlateText(veh))
```

### getBusinessVehicles

```lua theme={null}
---@return table: { 'ABC 123', … }
local plates = exports['aps_cityhall']:getBusinessVehicles(12)
```

### getPlayerBusinesses

```lua theme={null}
---@return table: { { id, name, category, status, role }, … }
local list = exports['aps_cityhall']:getPlayerBusinesses(source)
```

### getBusiness

```lua theme={null}
---@return table|nil: { id, name, owner, ownerName, category, status, job, permits, employees }
local biz = exports['aps_cityhall']:getBusiness('Downtown Cab Co')
```

***

## VIN, Paychecks & Job Center

### GenerateVIN

```lua theme={null}
---@return string: 17-character VIN
local vin = exports['aps_cityhall']:GenerateVIN()
```

> [!NOTE]
>
> See the [VIN](https://docs.aps-store.com/assets/aps_cityhall/guides/vin.md) guide for existing vehicles.

### updatePaychecks

Hands a salary to City Hall instead of the bank. See the [Paychecks](https://docs.aps-store.com/assets/aps_cityhall/guides/paychecks.md) guide.

```lua theme={null}
---@param action string|nil: nil = add, 'remove' = take away
---@return boolean
exports['aps_cityhall']:updatePaychecks(source, amount)
exports['aps_cityhall']:updatePaychecks(source, amount, 'remove')
```

### getPaycheckBalance

```lua theme={null}
local waiting = exports['aps_cityhall']:getPaycheckBalance(source)
```

### setResumeAllowed

```lua theme={null}
exports['aps_cityhall']:setResumeAllowed('police', false)   -- stop taking applications
```

### getJobResumes

```lua theme={null}
---@return table: applications, pending first
local list = exports['aps_cityhall']:getJobResumes('police')
```


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