Get Operator Competency Compliance Report

GET [ category-compliance-report ]

Production Endpoint: https://app.complyflow.com.au/app/public/index.php/api/acu/category-compliance-report?plant_category_id={id}
Test Endpoint: https://test.complyflow.com.au/app/public/index.php/api/acu/category-compliance-report?plant_category_id={id}

Overview

This endpoint returns the compliance status of Staff Users against the Operator Competencies required by a Plant Category, so you can report which operators hold current competencies for the plant they use.

Operator Competencies are the Document Categories a Plant Category requires from the Staff Users who operate its plant, for example a Competency Assessment or a High Risk Work Licence. They are configured on the Plant Category rather than a Staff Category, so they are not included when this endpoint is called with category_id. Call it with plant_category_id to report on them.

This is the same endpoint as the Staff Category Compliance Report, called with plant_category_id instead of category_id. The response uses the same structure, so the same reporting logic can be reused. Refer to Staff Category Compliance Report.

If you can't find what you are looking for or need further assistance, please contact support@complyflow.com.au

Authentication instructions

Refer to the Authentication method for Authentication Methods (for Login and Logout).

Permissions Required

API User
User is Staff
Staff > View Employees (previously Staff R), or Add & Edit Internal Employees (previously Staff RW)

Please also review the Permissions Overview guide.

Query parameters

FIELD	TYPE	DESCRIPTION	Example	REQUIRED	DEFAULT	PATTERN
`plant_category_id`	`integer`	Plant Category ID (must belong to your organisation). Refer to Get Plant Category List	12	Yes	`null`	`\d+`
`staff_id`	`integer`	Limit the report to one Staff User (must belong to your organisation)	1024	No	`null`	`\d+`
`page`	`integer`	Page number (minimum 1)	2	No	1	`\d+`
`per_page`	`integer`	Number of Staff Users per page (1 to 100)	100	No	50	`\d+`

Note: Send either plant_category_id or category_id, not both. With category_id, the endpoint returns the Staff Category Compliance Report instead. staff_id only applies with plant_category_id.

Request Example

All Staff Users assigned to the Plant Category:

curl --location 'https://test.complyflow.com.au/app/public/index.php/api/acu/category-compliance-report?plant_category_id=12&page=1&per_page=50' \
--header 'Authorization: Bearer {token}'

One Staff User:

curl --location 'https://test.complyflow.com.au/app/public/index.php/api/acu/category-compliance-report?plant_category_id=12&staff_id=1024' \
--header 'Authorization: Bearer {token}'

Response Example

The API request returns the Plant Category, its Operator Competencies, and the status of each Staff User assigned to the Plant Category:

{
  "token": "refreshed_jwt_token",
  "data": {
    "category": { "id": 12, "name": "Elevated Work Platforms", "type": "plant_category" },
    "required_documents": [
      { "id": 88, "name": "Competency Assessment - Boom Lift" },
      { "id": 91, "name": "High Risk Work Licence - Boom Lift (WP)" }
    ],
    "required_training": [],
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total": 2,
      "total_pages": 1
    },
    "members": [
      {
        "id": 1024,
        "name": "Jane Smith",
        "email": "jane.smith@example.com",
        "overall_status": "non_compliant",
        "documents": [
          {
            "document_category_id": 88,
            "document_category_name": "Competency Assessment - Boom Lift",
            "status": "compliant",
            "expiry_date": "2027-02-11",
            "approved_date": "2026-02-11",
            "approver": "Chris Lee"
          },
          {
            "document_category_id": 91,
            "document_category_name": "High Risk Work Licence - Boom Lift (WP)",
            "status": "missing",
            "expiry_date": null,
            "approved_date": null,
            "approver": null
          }
        ],
        "training": []
      },
      {
        "id": 1031,
        "name": "Sam Patel",
        "email": "sam.patel@example.com",
        "overall_status": "compliant",
        "documents": [
          {
            "document_category_id": 88,
            "document_category_name": "Competency Assessment - Boom Lift",
            "status": "expiring_soon",
            "expiry_date": "2026-10-05",
            "approved_date": "2025-10-06",
            "approver": "Chris Lee"
          },
          {
            "document_category_id": 91,
            "document_category_name": "High Risk Work Licence - Boom Lift (WP)",
            "status": "compliant",
            "expiry_date": "2029-05-20",
            "approved_date": "2024-05-22",
            "approver": "Chris Lee"
          }
        ],
        "training": []
      }
    ]
  }
}

Response Fields

Report Fields

Field Name	Type	Description
`category`	object	The Plant Category (`id`, `name`). `type` is always `plant_category` for this report
`required_documents`	array	The Plant Category's Operator Competencies (`id`, `name`). Returned even when no Staff Users are assigned to the Plant Category
`required_training`	array	Always empty for this report
`pagination`	object	`current_page`, `per_page`, `total` (number of Staff Users) and `total_pages`
`members`	array	One entry per Staff User on this page

Member Fields

Field Name	Type	Description
`id`	integer	Staff ID
`name`	string	Staff User's full name
`email`	string	Staff User's email address
`overall_status`	string	`compliant` or `non_compliant` (see Status Values)
`documents`	array	One entry per Operator Competency
`training`	array	Always empty for this report

Document Fields

Field Name	Type	Description
`document_category_id`	integer	Document Category ID of the Operator Competency
`document_category_name`	string	Operator Competency name
`status`	string	Compliance status (see Status Values)
`expiry_date`	string or null	Expiry date of the approved or expired document (YYYY-MM-DD). Null if the document has no expiry date
`approved_date`	string or null	Date the document was approved (YYYY-MM-DD)
`approver`	string or null	Full name of the person who approved the document

Status Values

Status	Meaning
`compliant`	An approved document is held and hasn't expired
`expiring_soon`	An approved document is held but expires within 30 days
`expired`	The most recent document has expired, and no approved or pending document is held
`pending_approval`	A document has been uploaded and is awaiting approval
`missing`	No document has been uploaded, or the most recent document was rejected

overall_status: compliant only if every Operator Competency is compliant or expiring_soon. Otherwise non_compliant.

Note: This report doesn't return a rejected status. A rejected document shows as missing, the same as in the Staff Category Compliance Report.

Error Responses

Errors are returned with HTTP status 200 in the standard response format, with the error details inside data, for example { "token": "...", "data": { "status": false, "error": "Either category_id or plant_category_id is required.", "error_code": 1 } }. If more than one parameter is invalid, only the first error is returned. Token errors are returned before the request reaches ComplyFlow, with the HTTP status shown.

Scenario	Response
Neither `plant_category_id` nor `category_id` supplied	`{ "status": false, "error": "Either category_id or plant_category_id is required.", "error_code": 1 }`
Both `plant_category_id` and `category_id` supplied	`{ "status": false, "error": "Validation failed.", "error_code": 1 }`
`plant_category_id` isn't an integer	`{ "status": false, "error": "The plant_category_id must be an integer.", "error_code": 1 }`
Plant Category isn't in your organisation	`{ "status": false, "error": "The specified plant category does not exist in your organisation.", "error_code": 2 }`
`staff_id` isn't an integer	`{ "status": false, "error": "The staff_id must be an integer.", "error_code": 1 }`
Staff User isn't in your organisation	`{ "status": false, "error": "The specified staff does not exist in your organisation.", "error_code": 2 }`
`page` isn't an integer, or is less than 1	`{ "status": false, "error": "The page must be an integer.", "error_code": 1 }` or `"The page must be at least 1."`
`per_page` isn't an integer, is less than 1, or is more than 100	`{ "status": false, "error": "The per_page must be an integer.", "error_code": 1 }`, `"The per_page must be at least 1."` or `"The per_page must not exceed 100."`
No API access, not a Staff User, or no Staff permission	`{ "status": false, "error": "Access denied", "error_code": 20 }`
No token supplied	HTTP 400 `{ "error": "token_not_provided" }`
Token has expired	HTTP 401 `{ "error": "token_expired" }`
Token is invalid, or has already been replaced by a refreshed token	HTTP 400 or 401 `{ "error": "token_invalid" }`

Usage Pattern (Power BI)

Call GET /api/acu/plant-categories to get all Plant Category IDs. Refer to Get Plant Category List
For each Plant Category, call GET /api/acu/category-compliance-report?plant_category_id={id}
Page through the results with &page=2, &page=3, etc. until current_page equals total_pages
Optionally add &staff_id={id} to report on one Staff User
Use the token returned in each response for your next request

To see every document required of a Staff User, combine this report with the Staff Category Compliance Report for each of their Staff Categories. Refer to Staff Category Compliance Report.

Notes

All results are scoped to your organisation via the JWT token
The report includes the Staff Users assigned to the Plant Category. These are the same Staff Users whose profiles list the Plant Category's Operator Competencies as Required Documents
Deleted and deactivated Staff Users are excluded
A Staff User assigned to more than one Plant Category appears in the report for each of them
With staff_id, members contains only that Staff User. It's empty if they aren't assigned to the Plant Category
Staff Users are returned in Staff ID order
If the Plant Category has no Operator Competencies, each Staff User's documents array is empty and overall_status is compliant
Documents with no expiry date are never shown as expired or expiring_soon
When no Staff Users are assigned to the Plant Category, members is empty and total_pages is 1
Requesting a page after the last page returns an empty members array
To report on the documents required for the Plant items themselves, refer to Get Plant Compliance Report