Written by CSM
This article describes how to use APIs to retrieve data from the allGeo system for integration with a Payroll system, Workforce Scheduling system or an ERP system.
Before the APIs can be used, following settings must be configured for the account. These settings are configured by the allGeo support team.
Enable API Access at the account level
White-list IP addresses to restrict API request origination from a specific IP Address or range.
Here is the common sequence of API calls that can be made once the API settings are complete.
Make login API call with account, Username and Password. If the call is successful, user is authenticated and a Token value is returned in the response.
Make non login API calls with token=<token value from login> request parameter along with other required parameters. Every API returns a JSON response with 2 fixed keys in it. They are status with an Integer value indicating the status of the request (0 = success) and message with a String value indicating success or failure reason. There may be other attributes depending on the API and they are documented in the API specification.
Let us walk through an example where the user wants to do the following. Let us also assume that we are conducting this exercise in demo account.
First step in the exercise is the request API access from Abaqus.
We will request allGeo Administrator to enable API access for account ‘demo.’
We will not white-list an IP Address or IP Address Range (less secure) so that we can make API calls from anywhere.
From a functional standpoint, we’ll do the following using APIs.
Add Devices to allGeo system using a CSV template
Add Job Sites
Add Daily Work-order assignment to the team
Get Daily Locaton Tracking & TimeClock reports from allGeo
To achieve above stated functionalities, here is the sequence of API call we have to make.
1. Login to allGeo via API
API URL: https://www.allgeo.com/ngui/login
Request Method: POST
API Parameters:
So, the API call will look like https://www.allgeo.com/ngui/login with account=demo&username=admin&password=<admin password> in the request body
If the above API call is successful you’ll get a JSON response as shown below
{ "status": 0,
"message": "Success",
"token": "384d27d5-5577-4713-8699-ff5e139d87ab"
}
You must store the “token” key value in persistent storage such as a database or in session because, you’ll need this value for all other API calls.
2. Add Devices to the Account (i.e. Employees)
Below API is used to add Employees and their phones to the account
Request call:
where a POST would be done and the .csv contents would be the template for device creation
* CSV Template
Below is the response we get from the Daily Schedule API call
{ "message":"Success",
"status":0 }
Below is the list of failure response we get from the locoptout api call
{ "message":"Failure",
"status":101 }
{ "message":"Device already exists",
"status":201 }
3. Setup Daily Schedule (i.e. Work-Order)
Below API is used to setup daily schedule / work-order assignment for employees
Request call:
URI -
https://api.allGeo.com/track/api/v1/dailyschedule/csv
where a POST would be done and the .csv contents would be the csv data
The CSV template is as follows:
Below is the response we get from the Daily Schedule API call
{ "message":"Success",
"status":0 }
Below is the list of failure response we get from the locoptout api call
{ "message":"Failure",
"status":101 }
{ "message":"Phone Number not found in the account",
"status":201 }
4. Location Opt out
Location Optout
Below API is used to optout the device from location services. It is PUT method call
Request call:
URI - http://www.allGeo.com/track/api/v1/device/{deviceID}/locoptout?token=Example URI : http://www.allGeo.com/track/api/v1/device/9876543210/locoptout?token=384d27d5-5577-4713-8699-ff5e139d87ab
M - Mandatory, O-Optional
Response:
Below is the response we get from the locoptout API call
{ "message":"Success",
"status":0 }
Below is the list of failure response we get from the locoptout API call
{ "message":"Failure",
"status":101 }
{ "message":"Phone Number not found in the account",
"status":201 }
5. Add Job Sites to the Account (i.e. Customer Site Geofences)
Below API is used to add geofenced Job Sites to the account
Request call:
URI - https://api.allGeo.com/track/api/v1/jobsites/csv
* CSV Template
where a POST would be done and the .csv contents would be the csv data
Below is the response we get from the Daily Schedule API call
{ "message":"Success",
"status":0 }
Below is the list of failure response we get from the locoptout api call
{ "message":"Failure",
"status":101 }
{ "message":"Site already exists",
"status":201 }