The API implements the REST architecture and provides an easy and intuitive way of communication with the GeoNext system via the HTTP protocol. By sending GET, POST, PATCH, PUT, and DELETE requests to various API endpoints it is possible to manipulate the corresponding data containers called items.

The API receives requests and responds in widely supported JSON format thus allowing the developers to write GeoNext-powered applications in almost any major programming language (such as Java, C#, C/C++, PHP, Perl, Python, Ruby, etc.) and for all major platforms, including Windows, Mac OS X, Linux, iPhone, Android and Windows Phone.

Head over to https://api.geoworkforce.io/oauth/applications and follow the registration steps or login with an existing GeoNext account to access the developer portal.

This document describes a early preview of the public API which is subject to change as more comprehensive developer features are introduced.

It is only possible to communicate with the API from a non-browser because CORS will prevent API calls originating from outside of the GeoNext domains.

For legacy reasons, some PUT endpoints behave like PATCH endpoints.

Query String Parameters that accepted comma-separated values are named <field>[] should be specified without the [] e.g. a query string parameter named for_model[] should be specified as ?for_model=.

An application willing to make requests to the GeoNext API will have to include an Authorization header with a unique access token so that each request can be authenticated and correct access permissions applied to that application.

The access token can be obtained from the GeoNext Authentication Server via the OAuth 2.0 protocol described in, Obtaining an access token

Roles

The protocol defines the following four roles:

• Resource Owner – a registered GeoNext user (employee, manager, company, administrator, etc.) or a system service.
• Resource Server – a GeoNext web server (https://api.geoworkforce.io) with access to the GeoNext database.
• Client – a native or third-party application or website utilising the GeoNext API.
• Authentication Server – a GeoNext web server (https://api.geoworkforce.io/oauth/token) responsible for authenticating incoming requests and issuing authorisation codes and access tokens (see below).

Using SSL/TLS security layer

Since access token acts as a session identifier and is used by the GeoNext Resource Server to load associated resource owner and client identities and permissions, it is crucial that this token is transferred only via a secured connection. Therefore, both the Authentication Server and the Resource Server require all requests to be made via a secured HTTPS connection.

Grant types

The GeoNext API oauth protocol implementation provides one way for a client to obtain an access token:

1. Authorisation Code Grant – a client redirects resource owner to the login page, receives an authorisation code from it via a redirect link and exchanges it for an access token.

For a third-party application to request an authorisation code, it has to be first registered with GeoNext and assigned a Client ID and Client Secret.

Any GeoNext account can be used a developer account regardless of that account's associated users.

1. Register for a GeoNext account at https://console.geoworkforce.io/signup
2. Navigate to the GeoNext Developer Portal at https://api.geoworkforce.io/oauth/applications and enter your developer credentials if requested.
3. Click "Create Application"
4. Enter in an Application name and Redirect URI. Multiple Redirect URI's can assigned, with each being seperated by a new line.
5. Click "Submit"
6. You will be redirected the Applications landing page where your newly created Application should appear. Clicking on the Application's name will reveal the Client ID and Client Secret.

An application that wants to get an authorisation code and later exchange it for an access token for GeoNext API has to redirect the resource owner to https://api.geoworkforce.io/oauth/authorize

The endpoint accepts the following parameters:

curl -L -X GET "https://api.geoworkforce.io/oauth/authorize?client_id=<CLIENT_ID>&response_type=code&redirect_uri=<REDIRECT_URI>"

Once the application has received an authorisation code as a parameter added to the redirect URI, it needs to exchange it for an access token, which it will then use to make requests to the GeoNext API. To do that, it has to make a POST request to the https://api.geoworkforce.io/oauth/token endpoint and include the following parameters:

The endpoint accepts the following parameters:

Example Request

curl --location --request POST 'https://api.geoworkforce.io/oauth/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id=<CLIENT_ID>' --data-urlencode 'client_secret=<CLIENT_SECRET>' --data-urlencode 'grant_type=authorization_code' --data-urlencode 'code=<AUTHORIZATION_CODE>' --data-urlencode 'redirect_uri=<REDIRECT_URI>'
}'

Example Response

{
    "access_token": "7fa3d3a64dd5e83fdb6e3ec2b71853015a058b43bfcdb171f40e3315f91db728",
    "token_type": "Bearer",
    "expires_in": 7200,
    "refresh_token": "dd12433b6493a1b2ec50d063cc7a3bca642515536c2a8302eb06f9ab92ae7507",
    "scope": "write",
    "created_at": 1585213246,
    "companies": []
}

If the application has received a refresh token, it may use the /oauth2/token endpoint to exchange it for a new access token once the current access token has expired. To do that, it has to make a https://api.geoworkforce.io/oauth/token request to the endpoint and include the following parameters:

The endpoint accepts the following parameters:

Example Request

curl --location --request POST 'https://api.geoworkforce.io/oauth/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'grant_type=refresh_token' --data-urlencode 'refresh_token=<REFRESH_TOKEN>'
}'

Example Response

    "access_token": "7fa3d3a64dd5e83fdb6e3ec2b71853015a058b43bfcdb171f40e3315f91db728",
    "token_type": "Bearer",
    "expires_in": 7200,
    "refresh_token": "dd12433b6493a1b2ec50d063cc7a3bca642515536c2a8302eb06f9ab92ae7507",
    "scope": "write",
    "created_at": 1585213246,
    "companies": []

If you wish to revoke an access token make an authenticated call to GET https://api.geoworkforce.io/oauth/logout and ignore any redirects.

OAuth 2 Website

RFC 6749 – OAuth 2 Specification

RFC 6750 – Bearer Token Usage Specification

There are limits to how many times an application can make API calls to each particular company.

• 1 call per second.
• 60 calls per minute.
• 5000 calls per day.

Once the call limit is reached the API will respond with http status code 429.

When you specify a Webhook URL for an application you will recieve begin to recieve API calls when an event for a company connected to your application is raised.

When an event occurs in GeoNext your webhook url will be called via a post containing the event name, a nonce, and a data object which typically only contains the resource identifier related to the event.

The following payload below states that a job was created with the identifier 117.

{
  "event_name": "job_created",
  "nounce": "7ebd27fe-435e-469e-af0d-76a875e9b44d"
  "data": {
    "id": 117
  }
}

Note that only a resource identifier is included in the data object. You can call the GeoNext API with a respective access token to interact with the resource further.

A header named X-Signature will be included in the call which is HMAC-SHA256 hashof the request payload using your application's secret as the signing key. You can repeat the hashing process and ensure your result matches the value of X-Signature to verify that the call originated from GeoNext.

Once you have confirmed the webhook call is genuine you can proceed with your implementation.

Your http status code response to the webhook call determines its success. Any http status code between 400-599 is considered a failure. All other http status codes are considered successes. If http status code 410 is recieved the webhook becomes permanently disabled.

Note: Some webhook calls can take upto 5 minutes to trigger. This is most evident with deletion. Therefore it is important to handle the case where a resource is no longer reachable.

GeoNext API supports OpenID Connect 1.0

During the Oauth2 authorization code request you can specify the openid scope.

During the Oauth2 access token request from an authorization code you will recieve an extra field id_token which contains an OpenID JWT.

The following endpoints relate to OpenID Connect functionality.

Some top-level API resources have support for bulk fetches via "list" endpoints. For instance, you can list jobs, clients, and list invoices. These list API methods share a common structure, taking at least these two query string parameters page and per_page.

Operations about Forms

A client represents your company's client base. Clients are typically assigned to jobs.

Jobs represent units of work to be completed for a clients. Billabes such as material, labour can be attached to a job to track resources committed to the task. Bookings are attached to a job to track which users worked on the job.

A job always has some job status assigned which helps you understand the current status of a job.

A staff member represents an employee in your company that can be assigned to jobs.