Introduction
The TrackTik reporting system and its API interfaces can be a bit daunting, but once you understand the approach that was taken in its design, it all becomes more clear and logical.
TrackTik’s Reports are based on three main data objects structures:
- Report Templates
- Report Template Fields
- Incident Categories (aka Report Flags)
From the parent objects Report Templates and Report Template Fields, you can create instances of them as Reports and Report fields.
Incident Categories are a data structure with an index that you can reference in a Report Field of type Incident Category.
Every Report you create will be based on its Report Template, and any Report Fields that Report contains, will be 1:1 matches with the Report Template Fields list, aligning on their datatypes.
The relationship between Report Templates to Reports is 1:N (many), and Report Template Fields are 1:N with Report Fields.
Glossary
TrackTik’s web and mobile apps use different vocabulary terms for various aspects of the reporting system. Here’s a handy table:
Web / Mobile UIs |
API |
Incident Category |
report-flags |
Parent Categories |
report-flag-categories |
Incident Groups |
report-flag-groups |
Incident Group, Incident Categories assignments |
report-flag-group-assignments |
Incident Category Subform |
report-flag-templates |
Incident Category Subform Custom Fields |
report-flag-template-fields |
Master Incident Category |
report-flags (with alias value defined) |
Retrieving Reports and Report Fields Data
The /reports endpoint will give you the metadata of reports. You can consider reports as containers, or parents, of their Report Fields (e.g. the data that at an Employee provides when filling out a report).
Report Fields are the N:1 of Reports, so you can include Report Fields data when requesting data on a Report, and view and edit the fields. The API also has a /report-fields endpoint if you’d like to look at Report Fields data directly, but not edit it.
Like most endpoints of TrackTik’s API, there is a LIST view (requesting many reports) and a SINGLE FETCH view (requesting one report). The Report Fields relation list only works with SINGLE FETCH view.
Getting a list of Reports (the metadata, without Report Fields) requires a filter of some kind to limit the list. In the next example I’ve used a date filter:
GET /reports?reportDateTime:after=2025-03-01
{
"reportTemplate": 63,
"timeZone": "America/New_York",
"reportDateTime": "2025-03-05T01:23:55-05:00",
"submitTime": 1741155835,
"submittedOn": "2025-03-05T06:23:55+00:00",
"account": 5,
"position": null,
"job": 152,
"approvedOn": null,
"approvalDateTime": null,
"status": "PENDING",
"approvedBy": null,
"checkpoint": null,
"reportFlag": null,
"siteLocation": null,
"uuid": "414ced44-a385-4412-9b54-5ad3aae2c263",
"id": 204
},
{
"reportTemplate": 63,
"timeZone": "America/New_York",
"reportDateTime": "2025-03-05T01:25:36-05:00",
"submitTime": 1741155936,
"submittedOn": "2025-03-05T06:25:36+00:00",
"account": 5,
"position": null,
"job": 153,
"approvedOn": null,
"approvalDateTime": null,
"status": "PENDING",
"approvedBy": null,
"checkpoint": null,
"reportFlag": null,
"siteLocation": null,
"uuid": "ac9b83e0-124e-445d-a069-2eec8c4d52d0",
"id": 205
}
etc.Most people will want to see a more complete picture of a report, including its Report Fields, so these need to be retrieved individually via a SINGLE FETCH like this (assume the ID of the report is 593):
[GET] /reports/593?include=reportFields
{
"reportTemplate": 28,
"timeZone": "America/New_York",
"account": 16,
"reportDateTime": "2018-08-23T10:54:23-04:00",
"submitTime": 1535036063,
"submittedOn": "2018-08-23T14:54:23+00:00",
"position": 17,
"approvedOn": "2018-08-23T14:54:23+00:00",
"approvalDateTime": "2018-08-23T14:54:23+00:00",
"status": "APPROVED",
"approvedBy": 1000,
"checkpoint": null,
"reportFlag": null,
"siteLocation": null,
"id": 593,
"reportFields": [
{
"fieldTag": "",
"report": 593,
"templateField": 29,
"value": {
"type": "text",
"value": "10:36"
},
"archived": false,
"id": 2776
},
{
"fieldTag": "",
"report": 593,
"templateField": 30,
"value": {
"type": "array",
"value": [
"Exterior Patrol"
]
},
"archived": false,
"id": 2777
},
{
"fieldTag": "",
"report": 593,
"templateField": 31,
"value": {
"type": "text",
"value": "NTR"
},
"archived": false,
"id": 2778
},
{
"fieldTag": "",
"report": 593,
"templateField": 32,
"value": {
"type": "text",
"value": "10:54"
},
"archived": false,
"id": 2779
},
etc.
]
}Tips for integrations and BI solutions:
If your integration requires that you regularly pull reports from the TrackTik system, then you should take a two step approach (given the limits of Report Fields relation list only being available in single item fetches, not lists):
First, retrieve the ID of reports via calls to /reports and store the ID of all these reports in an array of some kind. You can optimize the API call for this like so:
GET /reports?reportDateTime:after=2025-03-01&fields=id
Second, iterate through the array of IDs, making individual fetch calls of
GET /reports/$ID?include=reportFields
for each report.
The TrackTik API has a pagination system that you’ll have to take into account as well, further customizing the /reports call with limit=yy and offset=xx parameters. Here’s some additional documentation to help with that.
There are some hidden On Demand fields that you can add to the includes list if you like. More information on Report On Demand fields is available here and here.
Creating Reports and Report Fields
Creating a report requires that you provide the metadata for the parent report, and a certain format for the long form array or short form JSON object of Report Fields, which can be of differing types so sometimes you’ll provide a Resource ID or File ID to define a Report’s Report Field answer, or the literal text of the value. These all depend on the definition of the associated Report Template Fields.
Short Form
POST /reports
{
"reportTemplate": 164,
"account": 15,
"position": 11,
"reportFields": {
"166": "1566",
"165": "45",
"688": "12:50",
"951": "7287"
}
}OR
Long Form
{
"reportTemplate": 164,
"account": 15,
"position": 11,
"reportFields":[
{"field" : 166, "value": "1566"},
{"field" : 165, "value": "45"},
{"field" : 688, "value": "12:50"},
{"field" : 951, "value": "7287"}
]
}For fields identified by 166, 165 and 951, these are Resource IDs or sometimes a File ID – any kind of identifier for an object or list item defined in the associated report-template-field.
For 688, this is a text field. You need to be familiar with the report-template-fields definitions of report-template id=164 to know which to provide, in this example.
You can observe the results when you then fetch the report fields of the created report:
"reportFields": [
{
"fieldTag": "",
"report": 3589,
== "templateField": 166,
"value": {
"type": "resource",
"resource": "site-map-items",
== "resourceId": 1566,
"value": "Floor 1",
"uri": "https://tracktik.trial.local/rest/v1/site-map-items/1566"
},
"archived": false,
"id": 20722
},
{
"fieldTag": "",
"report": 3589,
== "templateField": 165,
"value": {
"type": "resource",
"resource": "report-flags",
== "resourceId": 45,
"value": "Ryann Staging Test (RYN-ST-001)",
"uri": "https://tracktik.trial.local/rest/v1/report-flags/45"
},
"archived": false,
"id": 20723
},
{
"fieldTag": "",
"report": 3589,
== "templateField": 688,
"value": {
"type": "text",
== "value": "12:50"
},
"archived": false,
"id": 20724
},
{
"fieldTag": "",
"report": 3589,
== "templateField": 951,
"value": {
"type": "image",
== "fileId": 7287,
"value": "https://tracktik.trial.local/rest/v1/media/7287/18635117ca54c1fdf50c5903e5827cc3a7429f94"
},
"archived": false,
"id": 20725
}
Patching Report Fields / Updating the Value of Report Fields
- Find the id of the report with the fields to change
- Take note of the account’s id. Let’s say it’s 123.
- Find the id of the report-template-field the report is based on that is linked to the field you wish to update. Let’s say it’s 1328.
- Combine the id of the report-template-field by prefixing the word “field” so that you have a new key in a “fieldxxxx” format where xxxx is the id of the report-template-field. Let’s say “field1328”.
- Format your JSON payload like the below and PATCH the report, remembering to include the array of reportFields
PATCH /reports/{id}
{
"reportFields" : [
{"field1328" : "new data"},
{"fieldxxxx"} : "xxxx"},
etc.
]
}NB: to remove a report field value, you can patch it to null like: {"field1328" : null}
Adding Additional Report Fields to Existing Reports
Even if a Report Template has had many Reports generated from them, you can still add additional Report Fields, and even to previously created reports.
It's a two step process:
- Add the new field(s) to the list defined in Report Template Fields
- Patch the Report with data for the new field(s) (TrackTik's software will take this UPDATE action and turn it into an ADD to the array of Report Fields of the Report)
First, add an additional field to Report Template Fields:
POST /report-template-fields
From the response of the POST, retain the id value (above: 2891).
Second, and as explained earlier in this document, you can PATCH the report and include this new field in the reportFields array like so:
PATCH /reports/{id}
Posting Back-Dated Reports
It’s possible. You just need to define all the time and date fields in the past with matching data:
E.g. this was posted on 2025-05-22 and back-dated to 2024-12-01 00:00:00
Removing a Report Field's Image
To remove an image from a report field, you need to patch the value with a NULL, like this:
Before
"reportFields": [
{
"fieldTag": "",
"report": 6223,
"templateField": 2867,
"value": {
"type": "text",
"value": "pictures test2"
},
"archived": false,
"id": 27369
},
{
"fieldTag": "",
"report": 6223,
"templateField": 2873,
"value": {
"type": "image",
"fileId": 14064,
"value": "https://innovation.staffr.net/rest/v1/media/14064/97d9ed00074776fe200f807177e1c1e439df79fd"
},
"archived": false,
"id": 27371
}
]After
"reportFields": [
{
"fieldTag": "",
"report": 6223,
"templateField": 2867,
"value": {
"type": "text",
"value": "pictures test2"
},
"archived": false,
"id": 27369
}
]When an image type report field is empty, it is removed from the array of reportFields.