Skip to main content
All endpoints require a valid Bearer token and the api.financial.invoices.manage permission. State-mutating requests must include a csrf_token — obtain one from GET /api/security/csrf-token.
Financial data in PropOps is tied directly to job records. Each job carries its own budget, contractor cost, VAT rate, and payment tracking fields. The Invoices API provides a consolidated view across all jobs with financial activity.

​
VAT Calculation

PropOps calculates VAT on every job using a configurable rate set by your administrator. The default rate is 20% (standard UK VAT rate). When you create or update a job, you can pass a vat_percentage field to override the default for that job. The computed total_amount reflects the contractor budget inclusive of VAT: 
total_amount = contractor_budget × (1 + vat_percentage / 100)
For example, a contractor budget of £180.00 at 20% VAT yields a total_amount of £216.00.

​
Invoice Immutability

Invoices in PropOps are immutable once issued. You cannot edit an invoice that has reached Invoiced status. To correct a mistake, void the original job’s invoice details and create a replacement record. This void-and-replace workflow ensures a complete audit trail for HMRC and accountancy review, as required for VAT-registered operations in the UK.

​
Invoices

​
List invoices

GET /api/financial/invoices?action=get_invoices Returns a paginated list of jobs with their invoice and payment data. Required permission: api.financial.invoices.manage
​
action
string
required
Must be get_invoices.
​
payment_status_id
integer
Filter by payment status ID (e.g. 1 = Awaiting Payment).
​
job_status_id
integer
Filter by the parent job’s status ID (e.g. 9 = Invoiced).
​
limit
integer
default:"50"
Maximum records to return (max 200).
​
offset
integer
default:"0"
Number of records to skip.
curl -X GET "https://propops.yourcompany.com/api/financial/invoices?action=get_invoices&payment_status_id=1&limit=25" \
  -H "Authorization: Bearer <token>"

{
  "success": true,
  "invoices": [
    {
      "id": 1001,
      "uuid": "550e8400-e29b-41d4-a716-446655440001",
      "job_ref": "JOB-001",
      "invoice_no": "INV-001",
      "job_title": "Boiler Service - Unit 001",
      "contractor_name": "Contractor_001",
      "contractor_budget": 180.00,
      "payment_received_client": 250.00,
      "payment_sent_contractor": 180.00,
      "agent_commission_paid": 25.00,
      "inhouse_commission_paid": 15.00,
      "status_name": "Invoiced"
    }
  ],
  "message": "Operation completed successfully"
}
​
invoices
array
Array of invoice objects.

​
Update payment fields

POST /api/financial/invoices Updates a single payment tracking field on a job. Call this endpoint each time you record a payment event (e.g. client payment received, contractor payment sent). Required permission: api.financial.invoices.manage
​
action
string
required
Must be update_payment.
​
job_id
integer
required
ID of the job to update.
​
field
string
required
The payment field to update. One of:
  • payment_received_client — Amount received from the client
  • payment_sent_contractor — Amount paid to the contractor
  • agent_commission_paid — Agent commission paid
  • inhouse_commission_paid — In-house commission paid
​
value
number
required
The new monetary value (e.g. 250.00).
​
csrf_token
string
required
CSRF token.
curl -X POST "https://propops.yourcompany.com/api/financial/invoices" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"action":"update_payment","job_id":1001,"field":"payment_received_client","value":250.00,"csrf_token":"<csrf-token>"}'

{
  "success": true,
  "message": "Payment field updated successfully"
}

​
Financial Reports

For aggregated financial reporting, use the Reports API: 
curl -X GET "https://propops.yourcompany.com/api/reports/financial" \
  -H "Authorization: Bearer <token>"

{
  "success": true,
  "data": [
    {
      "job_ref": "JOB-001",
      "job_title": "Boiler Service - Unit 001",
      "contractor_name": "Contractor_001",
      "invoice_no": "INV-001",
      "total_amount": 250.00,
      "contractor_budget": 180.00,
      "payment_received": true,
      "completed_date": "2024-06-02"
    }
  ],
  "message": "Operation completed successfully"
}
Use POST /api/analytics/ai-analysis with analysis_type=financial to trigger a Gemini AI-generated summary of your financial data, suitable for management review.