This readme contains important information about the Access Track API.
AccessTrack provides its clients with a RESTful API endpoint to retrieve scans in JSON format from the AT Integri system. In order to use the endpoint, the user requires valid credentials to access the system. There is also a Webhook functionality for real-time scan information.
Authenticating
The API endpoint requires a valid JWT token before it will return any results. This token is assigned to a specific user client. A user can specify a client or one can be automatically generated upon a successful token request.
Getting a JWT Token
To get a JWT token, a user needs to send his credentials with an HTTP POST request to https://portal.accesstrack.co.za/integri/api/token
The request needs to have the following header set: Content-Type: application/json
The body of the request must contain a JSON object with the user's credentials:
{
username: "myuser",
password: "mypassword",
uniqueId: "scanPoll"
}
The uniqueId is the client identifier. Use the uniqueId of an existing client if you have one. Alternatively enter any string name and a new client will be created for this user.
The response will contain a JSON object with the JWT token if it was successful:
{"token":"eyJhbGciOiJ...3dCbcXBUVLEEM"}
Refreshing the JWT token
The client's JWT token will expire after a preset amount of time (~one week). In addition to this, the token can expire after other events too e.g. a server restart. It is thus important that any tool that query the API will refresh the JWT token if the server reports that it is invalid (HTTP 401 or 403 response). DO NOT request a new token before every data request as this is an expensive operation.
Query Scan Groups
The ScanGroup endpoint allows users to query scan groups for their site(s) in a specified date range. Be careful not to query a too large range. The maximum number of scan groups that can be returned is 10000.
Make an HTTP POST request with the query parameters as a JSON object. The endpoint is located at https://portal.accesstrack.co.za/integri/api/scanGroup/scanGroups
The JWT token is sent with the request in the Authorization Header as a Bearer token. Include the following headers (replace the token with your own token): Content-Type: application/json, Authorization: Bearer eyJhbGciOiJ...3dCbcXBUVLEEM
The body of the request contains the parameters for the query. Here is an example:
{
siteId: 5,
fromDate: "2019-11-15",
toDate: "2019-11-15T23:59"
search: "parameter1,parameter2,..."
accessKey: "559740001"
}
The search parameter may contain multiple items in a comma-separated list that can be used to filter results. Records that match any of the terms in the list will be returned.
The accessKey is one of the items under an Access Category and can be used to provide additional refinement for search criteria.
The search and accessKey parameters are optional fields. Leaving one or both of will exclude them from the search and all records within the selected date range will be returned.
The data should be in the format as above. If the time is omitted, it is assumed to be 00:00. The siteId is also required. If you don't know your siteId, please see the section below to query your site details.
If the ScanGroup query is successful, the response will contain an array of scan group JSON objects. E.g.
[
{
"scanGroupId": 10664529,
"deviceId": "LEX820_98e973b1",
"location": "-25.8169350109518,28.2826083229487",
"username": "theUser",
"displayName": "The User",
"idNumber": "Unit 1",
"scannedName": "ML KAWOZA",
"licenceNumber": null,
"timestamp": "2021-08-18T12:26:22",
"departure": null,
"departureDeviceId": null,
"scanCount": 1,
"hourCount": 0.0,
"showWarning": false,
"hasBlacklist": false,
"expiryDate": null,
"sadlExpiryDate": null,
"fieldValues": "",
"addScan1": "Unit 1",
"addScan2": null,
"addScan3": null,
"isEmergency": false
},
{
"scanGroupId": 10664528,
"deviceId": "LEX820_98e973b1",
"location": "-25.8169350109518,28.2826083229487",
"username": "theUser",
"displayName": "The User",
"idNumber": "8208245266086",
"scannedName": "ML KAWOZA",
"licenceNumber": "NLW942GP",
"timestamp": "2021-08-12T16:04:03",
"departure": null,
"departureDeviceId": null,
"scanCount": 2,
"hourCount": 0.0,
"showWarning": false,
"hasBlacklist": false,
"expiryDate": "2018-04-30T00:00:00",
"sadlExpiryDate": null,
"fieldValues": "",
"addScan1": "8208245266086",
"addScan2": null,
"addScan3": null,
"isEmergency": false
}
]
Query Scans
The Scan endpoint allows users to query scans for their site(s) in a specified date range. Be careful not to query a too large range. The maximum number of scans that can be returned is 10000.
Make an HTTP POST request with the query parameters as a JSON object. The endpoint is located at https://portal.accesstrack.co.za/integri/api/scan/scans
The JWT token is sent with the request in the Authorization Header as a Bearer token. Include the following headers (replace the token with your own token): Content-Type: application/json, Authorization: Bearer eyJhbGciOiJ...3dCbcXBUVLEEM
The body of the request contains the parameters for the query. Here is an example:
{
siteId: 5,
fromDate: "2019-11-15",
toDate: "2019-11-15T23:59"
search: "parameter1,parameter2,..."
scanGroupId: "10664102"
}
The search parameter may contain multiple items in a comma-separated list that can be used to filter results. Records that match any of the terms in the list will be returned.
The scanGroupId will return all the scans related to a specific scan group and can be used to provide additional refinement for search criteria.
The search and scanGroupId parameters are optional fields. Leaving one or both of will exclude them from the search and all records within the selected date range will be returned.
The data should be in the format as above. If the time is omitted, it is assumed to be 00:00. The siteId is also required. If you don't know your siteId, please see the section below to query your site details.
If the Scan query is successful, the response will contain an array of scan group JSON objects. E.g.
[
{
"scanId": 41310077,
"scanGroupId": 10664109,
"user": "Username",
"timestamp": "2021-01-22T19:53:44",
"type": "SADL",
"barcode": "101705136971",
"surname": "PHEKANI",
"description": null
},
{
"scanId": 41310076,
"scanGroupId": 10664108,
"user": "Username",
"timestamp": "2021-01-22T19:51:48",
"type": "SAVL",
"barcode": "LN42XSGP",
"surname": null,
"description": "Sedan (closed top)"
}
]
Get your site details
Send a GET request to https://portal.accesstrack.co.za/integri/api/site/detail
Remember to include the Authorization and Content-Type headers. The response will contain a JSON object similar to this one:
{"id":5,"name":"Demo Site"}
Webhook
This feature is accessible via the web-portal and can be used to access scans in real-time.
You can enter multiple URL's and scan types. Once this is set up, every time the scanner sends a scangroup to the server it checks for webhooks and then send the requested scan-types (if available on the scangroup) to the specified URL.
An example of the output can be seen below:
{\"scanId\":41310903,\"scanGroupId\":10664521,\"user\":\"Christiaan\",\"timestamp\":\"2021-06-18T13:33:39Z\",\"type\":\"SADL\",\"barcode\":\"10170514036971\",\"surname\":\"PHEKANI\",\"description\":null}