Follow

API Reporting Reference

Checkit provides an API for retrieving an organisation’s Checkit data into the Operational Insight PowerBI platform, or into an organisation’s own Reporting systems.  This document is aimed at Technical staff in the organisation who have experience using APIs.

This article is also available in PDF form.

Access to the API

Requests to the API require use of an access Token, which is available from the Checkit Cloud Portal (Control Centre). The process to access the Token is documented in the Checkit Customer Support Portal https://checkithelpdesk.zendesk.com/hc/en-gb/articles/360000167713-How-to-retrieve-generate-your-authentication-token

Operational Insights API URL

The API is at https://reports.checkit.net

The API follows REST principles where each endpoint represents a resource – so returns a specific type of data.

The following endpoints are available:

  • https://reports.checkit.net/api/locations
  • https://reports.checkit.net/api/jobs
  • https://reports.checkit.net/api/reports

These are documented below.

GET /api/locations

Description: Returns all the Customer’s locations details, including any AM device information.

Accepts: text/csv (default), application/json

Response:

401 in case of invalid credentials

404 in case of invalid endpoint (/api/tomatoes)

500 in case of internal error

200 Location DTO:

{   _id,

name,

rptCount,

kCount,

rhCount,

bCount,

accountId,

accountName,

street,

city,

region,

country,

postcode,

phoneNumber,

branch1Name,

branch2Name,

branch3Name,

branch4Name,

branch1Id,

branch2Id,

branch3Id,

branch4Id,

}

 

GET /api/jobs

Description: Returns all jobs for the Customer, for a given set of parameters. A job is a Check or Checklist.

Accepts: text/csv (default), application/json

Query string:

limit: Number of results to return (default and maximum of 2,000,000)

start_time: default to two years ago (dd-MM-YY)

end_time: default to now 

 

Response:

401 in case of invalid credentials

404 in case of invalid endpoint (/api/tomatoes)

400 in case of invalid query parameters

500 in case of internal error

200 Job DTO:

{   _id,

status,

overdue,

observedTime,

scheduledCompletionTime,

team,

location,

locationId,

locationLeft,

locationRight,

schedule,

rootCheckName,

users,

}

  

GET /api/reports

Description: Return all reports for a given set of parameters. Checkit reports are records of completed checks and Alerts. Note that individual readings (Temperature, humidity) are not included.

Accepts: text/csv (default), application/json

Query string:

  • limit: Number of results to return (default and maximum of 2,000,000)
  • event_type: types of report to return (checkReport, jobOverdue, jobCancelled, sensorAlert, zigbeeBatteryAlert). Several can be provided through a comma-separated list.
  • service_type: module of which we want to retrieve reports: workmanagement or automatedmonitoring (internally, this value just sets the aforementioned event_type). Defaults to workmanagement.
  • start_time: default to two years ago (dd-MM-YY)
  • end_time: default to now (dd-MM-YY) 

Response:

401 in case of invalid credentials

404 in case of invalid endpoint (/api/tomatoes)

400 in case of invalid query parameters

500 in case of internal error

200 Report DTO which changes based on service type:

Work Management

{ _id,   

eventType,

    observedTime,

    observedTimeZoneId,

    raisesAlert,

    team,

    location,

    locationId,

    locationLeft,

    locationRight,

    canClear,

    clearedOn,

    acknowledgedOn,

    cleared,

    schedule,

    canraiseAlert,

    checkName,

    checkDescription,

    checkResponse,

    checkIsRoot,

    rootCheckName,

    jobId, 

    jobScheduledStartTime,

    jobScheduledCompletionTime,

    jobHandheldId

}

Automated Monitoring

{ _id,   

eventType,

    observedTime,

    observedTimeZoneId,

    raisesAlert,

    team,

    location,

    locationId,

    locationLeft,

    locationRight,

    canClear,

    backInRangeOn,

    clearedOn,

    acknowledgedOn,

    cleared,

    measurement,

    sensorName,

    sensorDescription,

    sensorMacAddress,

    sensorType,

    ruleName

}


Endpoint Data

Please see the attached spreadsheet for an explanation of the data returned by the API from the Reports, Jobs and Location endpoints.


Event Types

Event

Definition

Check Report

Work report entry for a checklist. When 'raisesAlert' is flagged as 'TRUE' this can be considered a Check Alert.

Job Overdue

Overdue Alert. Generated when a scheduled checklists becomes overdue.

Job Cancelled

Delayed Check specific command. The delayed check was cancelled before the delay completed.

Sensor Alert

Sensor Alert.  A sensor on an AM system has a reading out of range.

Service Alert

Service Alert.  Low Battery and No Data alerts from AM systems. zigbeeBatteryAlert

 Statuses

These are the possible values for Status types with an explanation what they mean. See Job Status for more details.

 

Definition

Status

Overdue (T/F)

Scheduled (T/F)

Completed  (unscheduled) complete F F
Completed Late complete T T
Completed on Time complete F T
Incomplete (scheduled) partiallyComplete T T
Incomplete (unscheduled) partiallyComplete  F F
Not Done/Started (Missed) expired T T
Cancelled (Delayed Check) cancelled F T

Unresolved Definitions

     
Due due F T
In Progress (Overdue) inProgress T T
In Progress (scheduled) inProgress F T
In Progress (unscheduled) inProgress F F
In Time to Complete (Overdue) due T T
Was this article helpful?
1 out of 1 found this helpful
Have more questions? Submit a request