Reports & Judicial System

File reports, manage warrants, handle license suspensions, process court appeals, and administer properties and businesses.

Authentication Required: All endpoints in this section require a valid JWT Bearer token via the authCheck middleware. Supervisor and admin-level endpoints are noted where applicable.

Report Types

CDE CAD supports a comprehensive set of report types organized into four categories. The reportType field on every report must be one of the values listed below.

Law Enforcement Reports

Report Type	Description
`written-warning`	Written warning issued to a civilian for a minor infraction
`citation`	Traffic or penal citation with fines and/or points
`arrest`	Full arrest report including charges, narrative, and booking info
`incident`	General incident report documenting a call for service or event
`search-warrant`	Application and execution details for a search warrant
`arrest-warrant`	Warrant for arrest issuance documentation
`crash`	Motor vehicle crash/accident report
`implied-consent`	Implied consent (chemical test refusal) documentation
`tow`	Vehicle tow and impound report
`trespass`	Trespass warning or order documentation
`cve`	Commercial vehicle enforcement inspection report
`dui`	Driving under the influence report with BAC and field sobriety data
`supplement`	Supplemental report attached to an existing case
`missing-person`	Missing person report and investigation details
`property-damage`	Property damage report documenting destroyed or damaged assets

Federal / Judicial Reports

Report Type	Description
`federal-indictment`	Federal indictment filing with charges and jurisdiction
`federal-warrant`	Federally-issued warrant for arrest or search
`restraining-order`	Restraining or protective order against a named party
`probation-report`	Probation status report including conditions and compliance
`grand-jury-subpoena`	Grand jury subpoena for testimony or documents
`court-order`	General court order documentation

EMS Reports

Report Type	Description
`patient-care`	Standard patient care report with assessment and treatment
`refusal`	Patient refusal of medical treatment or transport
`doa`	Dead on arrival report
`transport`	Patient transport report with origin, destination, and vitals
`mass-casualty`	Mass casualty incident (MCI) triage and response report
`overdose`	Overdose response report including substances and treatment
`psych-eval`	Psychiatric evaluation and involuntary hold documentation

Fire Reports

Report Type	Description
`fire-incident`	Fire department incident response report
`fire-investigation`	Post-fire investigation with cause and origin determination
`arson`	Arson investigation report with evidence and suspect info
`hazmat`	Hazardous materials response and containment report
`rescue`	Technical rescue operation report
`inspection`	Fire safety inspection report for a building or property
`code-violation`	Fire code violation notice and corrective action documentation

Report Endpoints

The /api/reports resource handles creation, retrieval, updating, deletion, search, and PDF generation for all report types.

GET /api/reports authCheck

List reports with filtering, pagination, and sorting. Rate limited to 60 requests per minute.

Query Parameters

Parameter	Type	Description
`communityId`	string	Required. The community to fetch reports for.
`reportType`	string	Filter by report type (e.g. `citation`, `arrest`).
`status`	string	Filter by status: `draft`, `submitted`, `approved`, or `denied`.
`page`	number	Page number for pagination (default: 1).
`limit`	number	Results per page (default: 20).
`sortBy`	string	Sort field (e.g. `dateTime`, `caseNumber`).

GET /api/reports?communityId=abc123&reportType=citation&status=submitted&page=1&limit=10&sortBy=dateTime

// Response
{
  "reports": [
    {
      "_id": "6612f...",
      "caseNumber": "RPT-2024-001432",
      "reportType": "citation",
      "status": "submitted",
      "officerName": "J. Smith",
      "badgeNumber": "4521",
      "dateTime": "2024-06-15T14:30:00Z",
      "subjectFirstName": "John",
      "subjectLastName": "Doe",
      ...
    }
  ],
  "total": 87,
  "page": 1,
  "pages": 9
}

POST /api/reports authCheck

Create a new report in draft status. The report can be edited before submission.

Request Body — Core Fields

Field	Type	Description
`reportType`	string	Required. One of the valid report types listed above.
`communityId`	string	Required. Community this report belongs to.
`officerId`	string	Required. ID of the filing officer.
`officerName`	string	Required. Full name of the filing officer.
`badgeNumber`	string	Required. Officer badge/unit number.
`department`	string	Required. Department name.
`dateTime`	string	Required. ISO 8601 date-time of the incident.
`location`	string	Location or address of the incident.
`zone`	string	Patrol zone.
`beat`	string	Beat designation.
`district`	string	District designation.
`weather`	string	Weather conditions at the time.
`lighting`	string	Lighting conditions (e.g. daylight, dark, artificial).

Request Body — Subject Fields

Field	Type	Description
`subjectFirstName`	string	Subject's first name.
`subjectLastName`	string	Subject's last name.
`subjectMiddleName`	string	Subject's middle name.
`subjectDOB`	string	Date of birth (YYYY-MM-DD).
`subjectGender`	string	Gender.
`subjectRace`	string	Race/ethnicity.
`subjectHeight`	string	Height (e.g. "5'10").
`subjectWeight`	string	Weight (e.g. "180 lbs").
`subjectHair`	string	Hair color.
`subjectEyes`	string	Eye color.
`subjectAddress`	string	Street address.
`subjectCity`	string	City.
`subjectState`	string	State.
`subjectZip`	string	ZIP code.
`subjectPhone`	string	Phone number.
`subjectLicense`	string	Driver's license number.
`subjectSSN`	string	Social Security number (stored encrypted).

Request Body — Vehicle Fields

Field	Type	Description
`vehiclePlate`	string	License plate number.
`vehicleState`	string	Registration state.
`vehicleMake`	string	Vehicle make (e.g. Ford).
`vehicleModel`	string	Vehicle model (e.g. Crown Victoria).
`vehicleYear`	string	Model year.
`vehicleColor`	string	Vehicle color.
`vehicleVIN`	string	Vehicle Identification Number.
`vehicleOwner`	string	Registered owner name.

Request Body — Details Fields

Field	Type	Description
`violations[]`	array	Array of violation objects (see structure below).
`narrative`	string	Officer narrative describing the incident.
`warningReason`	string	Reason for written warning (written-warning type).
`arrestNarrative`	string	Arrest-specific narrative (arrest type).
`fineAmount`	number	Total fine amount in dollars.
`jailTimeAmount`	number	Jail time in months.
`charges[]`	array	Array of charge strings.
`warrants[]`	array	Array of associated warrant IDs.
`images[]`	array	Array of image URLs (evidence, scene photos).

Violation Object Structure

{
  "code": "12-5-204",
  "description": "Speeding 20+ over posted limit",
  "severity": "misdemeanor",
  "fine": 500,
  "points": 4,
  "jailTime": 0
}

Example Request

POST /api/reports
Content-Type: application/json
Authorization: Bearer <token>

{
  "reportType": "citation",
  "communityId": "abc123",
  "officerId": "off_9821",
  "officerName": "Sgt. M. Rodriguez",
  "badgeNumber": "2847",
  "department": "Los Santos Police Department",
  "dateTime": "2024-06-15T14:30:00Z",
  "location": "Vespucci Blvd & Palomino Ave",
  "zone": "Zone 3",
  "beat": "B12",
  "district": "Vespucci",
  "weather": "Clear",
  "lighting": "Daylight",
  "subjectFirstName": "John",
  "subjectLastName": "Doe",
  "subjectDOB": "1990-05-12",
  "subjectGender": "Male",
  "subjectLicense": "DL-882910",
  "vehiclePlate": "SA1X234",
  "vehicleState": "San Andreas",
  "vehicleMake": "Declasse",
  "vehicleModel": "Vigero",
  "vehicleYear": "2019",
  "vehicleColor": "Red",
  "violations": [
    {
      "code": "12-5-204",
      "description": "Speeding 20+ over posted limit",
      "severity": "infraction",
      "fine": 500,
      "points": 4,
      "jailTime": 0
    }
  ],
  "narrative": "Subject was clocked at 87 MPH in a 65 MPH zone via radar. Subject was cooperative during the stop.",
  "fineAmount": 500
}

Response

// 201 Created
{
  "_id": "6612fa3b...",
  "caseNumber": "RPT-2024-001433",
  "status": "draft"
}

GET /api/reports/:id authCheck

Retrieve full details for a specific report by its ID.

GET /api/reports/6612fa3b...

// Response — full report object with all fields populated
{
  "_id": "6612fa3b...",
  "caseNumber": "RPT-2024-001433",
  "reportType": "citation",
  "status": "draft",
  "communityId": "abc123",
  "officerId": "off_9821",
  "officerName": "Sgt. M. Rodriguez",
  "badgeNumber": "2847",
  "department": "Los Santos Police Department",
  "dateTime": "2024-06-15T14:30:00Z",
  "location": "Vespucci Blvd & Palomino Ave",
  "subjectFirstName": "John",
  "subjectLastName": "Doe",
  "violations": [ ... ],
  "narrative": "...",
  "createdAt": "2024-06-15T14:35:00Z",
  "updatedAt": "2024-06-15T14:35:00Z"
}

PUT /api/reports/:id authCheck

Update an existing report. Any fields included in the request body will overwrite the existing values. Reports in approved or denied status cannot be edited.

PUT /api/reports/6612fa3b...
Content-Type: application/json
Authorization: Bearer <token>

{
  "narrative": "Updated narrative with additional witness statements.",
  "violations": [
    {
      "code": "12-5-204",
      "description": "Speeding 20+ over posted limit",
      "severity": "infraction",
      "fine": 500,
      "points": 4,
      "jailTime": 0
    },
    {
      "code": "12-3-101",
      "description": "Failure to signal lane change",
      "severity": "infraction",
      "fine": 150,
      "points": 2,
      "jailTime": 0
    }
  ],
  "fineAmount": 650
}

DELETE /api/reports/:id authCheck

Delete a report. Only reports in draft status can be deleted. Submitted, approved, or denied reports are permanent records.

DELETE /api/reports/6612fa3b...

// Response
{
  "success": true,
  "msg": "Report deleted successfully"
}

Draft only: Attempting to delete a non-draft report will return a 403 Forbidden error.

GET /api/reports/:id/pdf authCheck

Download the report as a formatted PDF document. The response content type is application/pdf.

GET /api/reports/6612fa3b.../pdf
Authorization: Bearer <token>

// Response: binary PDF file
// Content-Type: application/pdf
// Content-Disposition: attachment; filename="RPT-2024-001433.pdf"

GET /api/reports/search authCheck

Search reports across multiple fields. Supports text search on subject names, case numbers, officer names, and narrative content.

Parameter	Type	Description
`communityId`	string	Required. Community scope.
`q`	string	Free-text search query.
`reportType`	string	Filter by type.
`status`	string	Filter by status.
`officerId`	string	Filter by filing officer.
`startDate`	string	Start of date range (ISO 8601).
`endDate`	string	End of date range (ISO 8601).

GET /api/reports/search?communityId=abc123&q=speeding&reportType=citation&startDate=2024-01-01

GET /api/reports/by-subject authCheck

Retrieve all reports associated with a specific subject by their person ID. Useful for pulling a subject's complete report history.

Parameter	Type	Description
`subjectId`	string	Required. The subject/person ID.

GET /api/reports/by-subject?subjectId=per_88210

GET /api/reports/by-civilian authCheck

Retrieve all reports linked to a civilian character by their civilian ID.

Parameter	Type	Description
`civilianId`	string	Required. The civilian character ID.

GET /api/reports/by-civilian?civilianId=civ_55102

Report Approval Workflow

Reports follow a strict lifecycle from creation through final disposition. Each status transition triggers specific side effects in the system.

Workflow States

Status	Description	Editable
`draft`	Initial state. Report is being written and can be freely edited or deleted.	Yes
`submitted`	Report has been submitted for supervisor review. Can still be edited.	Yes
`approved`	Report approved by a supervisor. Becomes a permanent record. Side effects are triggered.	No
`denied`	Report denied by a supervisor with review notes. Permanent record.	No

Flow: draft → submitted → approved / denied

Submit a Report

To submit a draft report, update its status to submitted via the standard update endpoint:

PUT /api/reports/:id
Content-Type: application/json
Authorization: Bearer <token>

{
  "status": "submitted"
}

Approve a Report

PUT /api/reports/:id/approve supervisor / admin

Approve a submitted report. Requires supervisor or admin role. Triggers automated side effects on the subject's civilian record.

PUT /api/reports/6612fa3b.../approve
Authorization: Bearer <token>

// Response
{
  "success": true,
  "msg": "Report approved",
  "report": {
    "_id": "6612fa3b...",
    "caseNumber": "RPT-2024-001433",
    "status": "approved",
    "approvedBy": "Sgt. K. Williams",
    "approvedAt": "2024-06-16T09:00:00Z"
  }
}

Side Effects on Approval

When a report is approved, the system automatically performs the following actions:

Automated actions on report approval: These side effects happen immediately and cannot be individually reverted. If a report was approved in error, manual corrections will be needed.

Action	Description
Fine Deduction	The `fineAmount` is automatically deducted from the subject's civilian bank account balance. If the civilian has insufficient funds, the balance goes negative.
License Points	Violation points from each entry in the `violations[]` array are summed and added to the subject's driving record.
License Suspension	If the subject's accumulated license points exceed the community's configured threshold, the license is automatically suspended.
Discord Webhook	If the filing officer's department has a Discord webhook configured, a formatted embed is posted to the channel with the report summary, case number, and subject info.
Judicial Log	A `JudicialLog` entry is created recording the approval action, report details, and approving supervisor for audit purposes.

Judicial System

The /api/judicial resource handles license suspensions, arrest warrants, civilian court appeals, and audit logging for all judicial actions.

License Suspensions

Officers can request a license suspension for a civilian. Requests are reviewed by supervisors before taking effect.

POST /api/judicial/suspension-requests authCheck

Submit a license suspension request for review.

Field	Type	Description
`personId`	string	Required. The civilian/person ID.
`personName`	string	Required. Full name of the person.
`personLicense`	string	Required. License number being suspended.
`licenseType`	string	Required. One of: `drivers`, `firearms`, `cdl`, `hunting`, `fishing`, `offroad`, `boating`, `pilot`, `both`.
`reason`	string	Required. Reason for the suspension request.
`notes`	string	Additional notes or context.
`urgency`	string	Urgency level: `normal`, `high`, or `urgent`. Default: `normal`.

POST /api/judicial/suspension-requests
Content-Type: application/json
Authorization: Bearer <token>

{
  "personId": "per_88210",
  "personName": "John Doe",
  "personLicense": "DL-882910",
  "licenseType": "drivers",
  "reason": "Accumulated 18 points on driving record within 12 months",
  "notes": "Subject has 3 prior citations for speeding in the last 6 months",
  "urgency": "high"
}

// Response — 201 Created
{
  "_id": "susp_001",
  "status": "pending",
  "personId": "per_88210",
  "personName": "John Doe",
  "licenseType": "drivers",
  "urgency": "high",
  "requestedBy": "Sgt. M. Rodriguez",
  "createdAt": "2024-06-16T10:00:00Z"
}

GET /api/judicial/suspension-requests authCheck (supervisor)

List pending license suspension requests. Requires supervisor role.

GET /api/judicial/suspension-requests?communityId=abc123

// Response
{
  "suspensionRequests": [
    {
      "_id": "susp_001",
      "status": "pending",
      "personName": "John Doe",
      "licenseType": "drivers",
      "reason": "Accumulated 18 points on driving record within 12 months",
      "urgency": "high",
      "requestedBy": "Sgt. M. Rodriguez",
      "createdAt": "2024-06-16T10:00:00Z"
    }
  ]
}

PUT /api/judicial/suspension-requests/:id authCheck

Approve or deny a pending suspension request. When approved, the civilian's license status is immediately updated.

Field	Type	Description
`status`	string	Required. Set to `approved` or `denied`.
`reviewNotes`	string	Reviewer notes explaining the decision.

PUT /api/judicial/suspension-requests/susp_001
Content-Type: application/json
Authorization: Bearer <token>

{
  "status": "approved",
  "reviewNotes": "Points threshold exceeded. Suspension effective immediately."
}

// Response
{
  "success": true,
  "msg": "Suspension request approved. License has been suspended.",
  "suspensionRequest": {
    "_id": "susp_001",
    "status": "approved",
    "reviewedBy": "Lt. K. Williams",
    "reviewedAt": "2024-06-16T11:30:00Z",
    "reviewNotes": "Points threshold exceeded. Suspension effective immediately."
  }
}

POST /api/judicial/reinstate-license/:personId authCheck

Reinstate a previously suspended license for a civilian. Resets the suspension flag and optionally resets accumulated points.

POST /api/judicial/reinstate-license/per_88210
Authorization: Bearer <token>

// Response
{
  "success": true,
  "msg": "License reinstated for John Doe",
  "person": {
    "personId": "per_88210",
    "licenseStatus": "valid",
    "points": 0
  }
}

License Types: The licenseType field supports the following values: drivers, firearms, cdl, hunting, fishing, offroad, boating, pilot, and both (which suspends both drivers and firearms simultaneously).

Arrest Warrants

Officers and judicial staff can issue, query, resolve, and delete arrest warrants. Active warrants appear in lookup results for the named person.

POST /api/judicial/warrants authCheck

Issue a new arrest warrant for a person.

Field	Type	Description
`personId`	string	Required. The person/civilian ID.
`personName`	string	Required. Full name of the person.
`charges[]`	array	Required. Array of charge objects.

Charge Object Structure

{
  "code": "18-4-302",
  "description": "Aggravated Assault",
  "severity": "felony"
}

Example Request

POST /api/judicial/warrants
Content-Type: application/json
Authorization: Bearer <token>

{
  "personId": "per_88210",
  "personName": "John Doe",
  "charges": [
    {
      "code": "18-4-302",
      "description": "Aggravated Assault",
      "severity": "felony"
    },
    {
      "code": "18-8-208",
      "description": "Evading a Peace Officer",
      "severity": "misdemeanor"
    }
  ]
}

// Response — 201 Created
{
  "_id": "war_0042",
  "personId": "per_88210",
  "personName": "John Doe",
  "charges": [ ... ],
  "status": "active",
  "issuedBy": "Judge A. Thompson",
  "issuedAt": "2024-06-16T12:00:00Z"
}

GET /api/judicial/warrants authCheck

Retrieve all active warrants for the community. Optionally filter by person.

GET /api/judicial/warrants?communityId=abc123

// Response
{
  "warrants": [
    {
      "_id": "war_0042",
      "personId": "per_88210",
      "personName": "John Doe",
      "charges": [
        { "code": "18-4-302", "description": "Aggravated Assault", "severity": "felony" }
      ],
      "status": "active",
      "issuedBy": "Judge A. Thompson",
      "issuedAt": "2024-06-16T12:00:00Z"
    }
  ]
}

PUT /api/judicial/warrants/:id/resolve authCheck

Mark a warrant as resolved (e.g., subject arrested or warrant recalled). The warrant remains in the system as a historical record but no longer appears in active warrant checks.

PUT /api/judicial/warrants/war_0042/resolve
Authorization: Bearer <token>

// Response
{
  "success": true,
  "msg": "Warrant resolved",
  "warrant": {
    "_id": "war_0042",
    "status": "resolved",
    "resolvedBy": "Ofc. P. Chen",
    "resolvedAt": "2024-06-17T08:45:00Z"
  }
}

DELETE /api/judicial/warrants/:id authCheck

Permanently delete a warrant. Use with caution — for most cases, resolving a warrant is preferred to preserve the audit trail.

DELETE /api/judicial/warrants/war_0042
Authorization: Bearer <token>

// Response
{
  "success": true,
  "msg": "Warrant deleted"
}

Destructive action: Deleting a warrant permanently removes it from the system. Consider using the /resolve endpoint instead to maintain a complete judicial record.

Court Requests (Civilian Appeals)

Civilians can submit appeals against reports (citations, arrests, etc.) through the court request system. Judicial staff review, schedule hearings, and issue rulings.

POST /api/judicial/court-requests authCheck

Submit a new court appeal against a report.

Field	Type	Description
`civilianId`	string	Required. The civilian character ID filing the appeal.
`civilianName`	string	Required. Full name of the civilian.
`reportId`	string	Required. ID of the report being appealed.
`reportCaseNumber`	string	Required. Case number of the report.
`reportType`	string	Required. The type of report being appealed.
`appealReason`	string	Required. Detailed reason for the appeal.

POST /api/judicial/court-requests
Content-Type: application/json
Authorization: Bearer <token>

{
  "civilianId": "civ_55102",
  "civilianName": "John Doe",
  "reportId": "6612fa3b...",
  "reportCaseNumber": "RPT-2024-001433",
  "reportType": "citation",
  "appealReason": "The radar reading was inaccurate. I was driving at the posted speed limit and have dashcam footage to support my claim."
}

// Response — 201 Created
{
  "_id": "court_0018",
  "civilianName": "John Doe",
  "reportCaseNumber": "RPT-2024-001433",
  "status": "pending",
  "createdAt": "2024-06-17T10:00:00Z"
}

GET /api/judicial/court-requests authCheck

Retrieve pending court requests for a community.

GET /api/judicial/court-requests?communityId=abc123

// Response
{
  "courtRequests": [
    {
      "_id": "court_0018",
      "civilianId": "civ_55102",
      "civilianName": "John Doe",
      "reportId": "6612fa3b...",
      "reportCaseNumber": "RPT-2024-001433",
      "reportType": "citation",
      "appealReason": "The radar reading was inaccurate...",
      "status": "pending",
      "createdAt": "2024-06-17T10:00:00Z"
    }
  ]
}

PUT /api/judicial/court-requests/:id authCheck

Update a court request — schedule a hearing date, add notes, or issue a final ruling.

PUT /api/judicial/court-requests/court_0018
Content-Type: application/json
Authorization: Bearer <token>

{
  "status": "scheduled",
  "hearingDate": "2024-06-25T14:00:00Z",
  "judgeNotes": "Hearing scheduled. Civilian to present dashcam evidence."
}

// Example: Issuing a ruling
PUT /api/judicial/court-requests/court_0018

{
  "status": "ruled",
  "ruling": "sustained",
  "rulingNotes": "Evidence reviewed. Citation overturned. Fine to be refunded.",
  "ruledBy": "Judge A. Thompson",
  "ruledAt": "2024-06-25T15:30:00Z"
}

Judicial Logs

All judicial actions (report approvals, suspension decisions, warrant issuances, court rulings) are logged for audit purposes.

GET /api/judicial/logs authCheck

View the full judicial action history for a community. Returns a chronological log of all judicial actions taken.

GET /api/judicial/logs?communityId=abc123

// Response
{
  "logs": [
    {
      "_id": "log_0091",
      "action": "report_approved",
      "reportId": "6612fa3b...",
      "caseNumber": "RPT-2024-001433",
      "performedBy": "Lt. K. Williams",
      "details": "Citation report approved. $500 fine deducted. 4 points added.",
      "timestamp": "2024-06-16T09:00:00Z"
    },
    {
      "_id": "log_0092",
      "action": "suspension_approved",
      "personId": "per_88210",
      "personName": "John Doe",
      "performedBy": "Lt. K. Williams",
      "details": "Driver's license suspended. 18 points accumulated.",
      "timestamp": "2024-06-16T11:30:00Z"
    },
    {
      "_id": "log_0093",
      "action": "warrant_issued",
      "personId": "per_88210",
      "personName": "John Doe",
      "performedBy": "Judge A. Thompson",
      "details": "Arrest warrant issued for Aggravated Assault (felony), Evading a Peace Officer (misdemeanor).",
      "timestamp": "2024-06-16T12:00:00Z"
    },
    {
      "_id": "log_0094",
      "action": "court_ruling",
      "courtRequestId": "court_0018",
      "performedBy": "Judge A. Thompson",
      "details": "Citation RPT-2024-001433 overturned. Fine refunded.",
      "timestamp": "2024-06-25T15:30:00Z"
    }
  ]
}

Properties

The /api/properties resource manages civilian-owned real estate. Properties can be created, listed for sale, and purchased by other civilians.

GET /api/properties/civilian/:civilianId authCheck

Retrieve all properties owned by a specific civilian.

GET /api/properties/civilian/civ_55102

// Response
{
  "properties": [
    {
      "_id": "prop_001",
      "address": "124 Grove Street",
      "city": "Los Santos",
      "type": "residential",
      "value": 250000,
      "ownerId": "civ_55102",
      "ownerName": "John Doe",
      "forSale": false,
      "createdAt": "2024-03-10T08:00:00Z"
    }
  ]
}

POST /api/properties authCheck

Create a new property record and assign it to a civilian.

POST /api/properties
Content-Type: application/json
Authorization: Bearer <token>

{
  "communityId": "abc123",
  "address": "124 Grove Street",
  "city": "Los Santos",
  "type": "residential",
  "value": 250000,
  "ownerId": "civ_55102",
  "ownerName": "John Doe"
}

// Response — 201 Created
{
  "_id": "prop_001",
  "address": "124 Grove Street",
  "value": 250000,
  "ownerId": "civ_55102",
  "forSale": false
}

PUT /api/properties/:id/list authCheck

List a property for sale. Sets the forSale flag and optionally updates the asking price.

PUT /api/properties/prop_001/list
Content-Type: application/json
Authorization: Bearer <token>

{
  "askingPrice": 275000
}

// Response
{
  "success": true,
  "msg": "Property listed for sale",
  "property": {
    "_id": "prop_001",
    "forSale": true,
    "askingPrice": 275000
  }
}

POST /api/properties/:id/purchase authCheck

Purchase a listed property. The purchase price is deducted from the buyer's bank account and credited to the seller's account. Ownership is transferred.

POST /api/properties/prop_001/purchase
Content-Type: application/json
Authorization: Bearer <token>

{
  "buyerId": "civ_77301",
  "buyerName": "Jane Smith"
}

// Response
{
  "success": true,
  "msg": "Property purchased successfully",
  "property": {
    "_id": "prop_001",
    "address": "124 Grove Street",
    "ownerId": "civ_77301",
    "ownerName": "Jane Smith",
    "forSale": false,
    "purchasePrice": 275000,
    "purchasedAt": "2024-06-18T14:00:00Z"
  }
}

Insufficient funds: If the buyer's bank balance is less than the asking price, the purchase will fail with a 400 error.

Businesses

The /api/business resource manages civilian-operated businesses including license applications, employee management, and financial records.

POST /api/business/request authCheck

Apply for a business license. The request is reviewed by community admins before approval.

POST /api/business/request
Content-Type: application/json
Authorization: Bearer <token>

{
  "communityId": "abc123",
  "civilianId": "civ_55102",
  "civilianName": "John Doe",
  "businessName": "Doe's Auto Repair",
  "businessType": "automotive",
  "address": "456 Strawberry Ave, Los Santos",
  "description": "Full-service auto repair and custom modification shop"
}

// Response — 201 Created
{
  "_id": "biz_0012",
  "businessName": "Doe's Auto Repair",
  "status": "pending",
  "ownerId": "civ_55102",
  "createdAt": "2024-06-19T09:00:00Z"
}

GET /api/business/civilian/:civilianId authCheck

Retrieve all businesses owned by or associated with a civilian.

GET /api/business/civilian/civ_55102

// Response
{
  "businesses": [
    {
      "_id": "biz_0012",
      "businessName": "Doe's Auto Repair",
      "businessType": "automotive",
      "status": "approved",
      "address": "456 Strawberry Ave, Los Santos",
      "ownerId": "civ_55102",
      "ownerName": "John Doe",
      "employees": 3,
      "createdAt": "2024-06-19T09:00:00Z"
    }
  ]
}

POST /api/business/:businessId/employees authCheck

Add an employee to a business. The requesting user must be the business owner or a manager.

POST /api/business/biz_0012/employees
Content-Type: application/json
Authorization: Bearer <token>

{
  "civilianId": "civ_77301",
  "civilianName": "Jane Smith",
  "role": "mechanic",
  "salary": 3500
}

// Response — 201 Created
{
  "success": true,
  "msg": "Employee added",
  "employee": {
    "civilianId": "civ_77301",
    "civilianName": "Jane Smith",
    "role": "mechanic",
    "salary": 3500,
    "hiredAt": "2024-06-20T10:00:00Z"
  }
}

GET /api/business/:businessId/financials authCheck

Retrieve financial records for a business including revenue, expenses, payroll, and balance history.

GET /api/business/biz_0012/financials

// Response
{
  "businessId": "biz_0012",
  "businessName": "Doe's Auto Repair",
  "balance": 47500,
  "financials": {
    "totalRevenue": 125000,
    "totalExpenses": 77500,
    "payroll": {
      "totalEmployees": 3,
      "monthlyCost": 10500
    },
    "recentTransactions": [
      {
        "type": "revenue",
        "amount": 2500,
        "description": "Vehicle repair - Engine rebuild",
        "date": "2024-06-20T16:00:00Z"
      },
      {
        "type": "expense",
        "amount": 800,
        "description": "Parts order - Pistons and gaskets",
        "date": "2024-06-20T11:00:00Z"
      },
      {
        "type": "payroll",
        "amount": 3500,
        "description": "Salary payment - Jane Smith",
        "date": "2024-06-15T00:00:00Z"
      }
    ]
  }
}