GeoNext (1.0.0)

Download OpenAPI specification:Download

Introduction

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.

Register as a Developer

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.

Important Notes

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=.

Authentication

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.

Client Registration

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.

Obtaining an authorization code

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:

Parameter Required Description
client_id Required The Application's client id.
redirect_uri Required A redirect URI whitelisted in the Application's configuration.
response_type Required The desired response type. This should be 'code'.
scope Optional The desired scopes the Application wants access to. This defaults to every scope the Application can request.
curl -L -X GET "https://api.geoworkforce.io/oauth/authorize?client_id=<CLIENT_ID>&response_type=code&redirect_uri=<REDIRECT_URI>"

Obtaining an access token

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:

Parameter Required Description
client_id Required The Application's client id.
client_secret Required The Application's client secret.
grant_type Required The desired grant type. This should be 'authorization_code'.
redirect_uri Required The redirect_uri used to generate the authorization code.
code Required A valid authorization code.

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": []
}

Refreshing an access token

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:

Parameter Required Description
grant_type Required The desired grant type. This should be 'refresh_token'.
refresh_token Required A valid refresh token.

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": []

Revoking an access token

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

API Limits

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.

Webhooks

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.

Recieving a Webhook Call

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.

Supported Event Names

Entity Action Event Name
Job Create job_created
Job Update job_updated
Job Delete job_deleted
Job Status Create job_status_created
Job Status Update job_status_updated
Job Status Delete job_status_deleted
Job Booking Create job_visit_created
Job Booking Update job_visit_created
Job Booking Delete job_visit_created
Client Create client_created
Client Update client_updated
Client Delete client_deleted
User Create user_created
User Update user_updated
User Delete user_deleted

OpenID Connect 1.0

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.

Endpoint Description
GET https://api.geoworkforce.io/oauth/userinfo Retrieve information related to the authenticated user.
GET https://api.geoworkforce.io/oauth/discovery/keys OpenID Discovery.
GET https://api.geoworkforce.io/.well-known/openid-configuration https://tools.ietf.org/html/rfc5785
GET https://api.geoworkforce.io/.well-known/webfinger https://tools.ietf.org/html/rfc5785

Pagination

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.

Clients

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

Bullk delete clients

Bulk delete clients

query Parameters
origin
string

Where Client originated from, e.g. xero, myob

Request Body schema: application/x-www-form-urlencoded
ids[]
Array of integers <int32>

List of ids to delete

Responses

Create a client

Create a client

Request Body schema: application/x-www-form-urlencoded
first_name
string

Name

last_name
string

Name

company_name
string

Company

email
string

Email

dob
string

Date of Birth

mobile_number
string

Mobile Number without the country code. Country code will be based on the set Country

landline_number
string

Phone number

country
string

Must be country code

physical_address[unit_number]
string
physical_address[address1]
string
physical_address[address2]
string
physical_address[city]
string
physical_address[state]
string
physical_address[postcode]
string
physical_address[country]
string
physical_address[latitude]
number <float>
physical_address[longitude]
number <float>
mailing_address[unit_number]
string
mailing_address[address1]
string
mailing_address[address2]
string
mailing_address[city]
string
mailing_address[state]
string
mailing_address[postcode]
string
mailing_address[country]
string
mailing_address[latitude]
number <float>
mailing_address[longitude]
number <float>
mobile_phones[][id]
Array of strings
mobile_phones[][number]
required
Array of strings
mobile_phones[][primary_contact]
Array of booleans
fax
string

Fax number

website
string

Website

business_type
string

Business Type

lead_source
string

Lead source

notes
string

Notes

billed_client_id
integer <int32>

The id of the client to bill to

alternative_contact_id
string

Alternative Contact (Client Id)

code
string

Client Code

medical_conditions
string

Medical conditions and allergies

upload_avatar
string <binary>

Client profile picture

budget
integer <int32>

Budget hours