Overview

Introduction Requests Responses & Error Handling Endpoint Versioning Registration Authorisation (connecting) Endpoint Authentication

Endpoints

EZICHEQ API

Introduction

The EZICHEQ API enables developers to integrate a web-based application ("app") with the EZICHEQ platform. Use this to keep your app data in sync with EZICHEQ.

                EZICHEQ

For Programmers: If you are a programmer and have the tooling, you can use our openapi.json file to generate code that interfaces to our API. Search on google for OpenAPI or OAS3 or Swagger and you'll find numerous tools and services that can write this code for you, automatically. If you do you should still read the rest of this introduction. Of course you can also write code manually which is why we provide the rest of this website for you.

For Non-Programmers: If you are not a programmer, you can still work with our API via Zapier, which allows you to plug your EZICHEQ account into any one of their thousands of integrations, such as your Gmail or your Xero account. Our Zapier integration covers less functionality than our REST API does, but the basics are available and if you need more don't hesitate to contact us at info@ezicheq.com.

RESTful: Primary functionality is enabled with HTTP endpoints that operate in a RESTful fashion.

OAuth2: Authentication and Authorisation is handled in a very standard way using OAuth2 defined by RFC 6749 . You don’t need to comb through IETF standards to understand how this works as we will walk you through it, but the standard is there if you need more detail and precision.

Web Applications Only: The EZICHEQ API currently does not support smartphone apps, nor JavaScript browser apps. OAuth2 provides separate protocols and grant types for those situations which we have not yet implemented. The grant types we have implemented require us to redirect a user’s browser to a URL within your application, which is only possible if your application is a Web based application that services URLs. We may support smartphone apps and JavaScript browser apps in a future release.

Must be an EZICHEQ user: You must be an EZICHEQ user to register an app with our API. Once registered, any other EZICHEQ user can authorise your app to use the EZICHEQ API via their EZICHEQ account.

Limits and Terms

  • Endpoints which list records are limited to 100 records at a time, and support paging via a 'page' parameter. Paging starts at page=1.
  • API accesses may be logged. These logs are not yet available for query.
  • API accesses may be throttled. Details as to the maximum rate will be supplied at a later time.
  • We may disable or remove an app if we determine that it is misbehaving. Please refer to our Terms of Use.

Other Details

  • No list of apps: We don’t currently list or promote connected apps — for the moment you need to start the integration process on your side.
  • British spelling: Note that within the OAuth2 protocol, authorization is spelled using the American spelling (with a zed — ’z’). Within our documentation, we use the British / New Zealand spelling (with an ess — ’s’).

Requests

In general:

  • GET requests fetch data and utilise URL query parameters
  • GET requests with an ID fetch a specific record
  • GET requests without an ID fetch a list of records
  • POST requests are used to create new records, but also for other purposes
  • PUT requests are used to update/modify existing records. Only the fields needing to be changed need to be supplied. (PUT is idempotent - If you make the same request many times, the result is the same as if you only did it once).
  • DELETE requests are used to delete records
  • OPTIONS requests are used to explore the verbs available at an endpoint
  • HEAD requests are identical to GET requests, except with an empty body
  • We don't service PATCH requests. Some APIs use PATCH instead of PUT for subsets of data. The EZICHEQ API uses PUT.

Responses and Error Handling

Responses are in JSON format, even if you set a different Accept header (which we currently ignore). Each response contains both a result and an error field, but either or both of these may be null. Each response also contains a number of metadata fields such as status_code, status, date, request_method, request_uri and count. You may also see a warning field from time to time, which will contain an array of warnings.

HTTP status codes are also used. The HTTP status code can be used to determine the nature of the error so that your app can handle different kinds of errors differently.

Endpoint Versioning

Rather than version our entire API, we have chosen to version each endpoint category. This allows us to roll out updates in smaller batches. When we update an endpoint version, the existing version will generally remain operational, unless we determine that it presents a security or data integrity problem. We intend to mark deprecated endpoints as such in the openapi.json spec.

Endpoint URLs are in the format /category/version. Versions start with the letter ’v’ followed by an integer starting from 1.

Example: /company/v1

If an ID is required, this is supplied next on the URL.

Example: /company/v1/abc-def-ghi-1234567

Registration

In order to access the EZICHEQ API, developers first need to register their App with us. This happens at the Registration page. You don’t have to wait for approval — as soon as you complete the form, registration is complete. You also have the ability to delete registrations that you create.

Registering an app does not grant it any access to the EZICHEQ API, nor does it list your app anywhere other than under your own list of apps.

During registration, you tell us:

  • Your Application’s name
  • Your Application’s redirect_uri
The redirect_uri is explained more under Authorisation (connecting)

Once you submit the registration form, we provide to you:

  • A unique client_id
  • A client_secret
We also provide the following general information, which you will need in order to integrate with our OAuth2 implementation:
  • Grant Types: Authorisation Code, Refresh Token
  • Authorisation Code endpoint: https://ezicheq.com/api/authorise
  • Token endpoint: https://api.ezicheq.com/oauth2/token
  • Refresh Token endpoint: https://api.ezicheq.com/oauth2/token
  • Scope: not required; ignored if supplied

Authorisation (connecting)

Authorisation is where a user authorises your app to connect to EZICHEQ through their account.

This process starts at your application. Redirect the user’s browser to our Authorisation Code endpoint and pass in via URL query parameters the following data:

  • response_type = the literal string "code"
  • client_id = your client_id that you got during registration
  • state = Anything you choose. This is provided so you can use it to protect against cross-site request forgery. You should provide something random and unique, and then verify it when we pass it back to you in a later step.
  • redirect_uri = A URI within your web application where we will redirect the user once they have completed this part of the process on our side.

After interacting with the user to verify that they wish to authorise this connection, we will redirect their browser back to your redirect_uri with a code URL query parameter. At this point you have 30 seconds to utilise this authorisation code before it expires.

To utilise the authorisation code, you need to present it at our token endpoint. POST to our token endpoint with the following body parameters in application/x‑www‑form‑urlencoded format:

  • grant_type = the literal string "authorization_code"
  • client_id = your client_id that you got during registration
  • code = the code you got in the redirect from the last step
  • redirect_uri = The redirect URI used earlier. It must match what was used earlier. It will not be used this time around as we will reply directly to this request.
You'll need to supply Basic Authentication credentials consisting of your Client ID and Client Secret.

Our reply will be JSON formatted and contain the following response data:

  • access_token = This is the token you must send in with every HTTP API endpoint request in order to identify your app and the user who is using it.
  • expires_in = This is the number of seconds after which the access_token will expire. Expect this to be 3600 (one hour)
  • token_type = This will always be "Bearer"
  • scope = This indicates what company within EZICHEQ the application has access to, and what role. It is formatted as "company_id:role".
  • refresh_token = This is a long-lived token that you must keep in order to refresh access_tokens as they expire.

Refreshing an expired Access Token

Once your access token expires, you can get a new one by presenting the refresh_token. The process of doing so consumes the refresh_token (they are one-time use), but provides a new one in return.

POST to the token endpoint with the following body parameters in application/x‑www‑form‑urlencoded format:

  • grant_type = the literal string "refresh_token"
  • refresh_token = your current refresh_token
You'll need to supply Basic Authentication credentials consisting of your Client ID and Client Secret.

Our reply will be JSON formatted and contain the following response data:

  • access_token = This is the token you must send in with every HTTP API endpoint request in order to identify your app and the user who is using it.
  • expires_in = This is the number of seconds after which the access_token will expire. Expect this to be 3600 (one hour)
  • token_type = This will always be "Bearer"
  • scope = This indicates what company within EZICHEQ the application has access to, and what role. It is formatted as "company_id:role".
  • refresh_token = This is a long-lived token that you must keep in order to refresh access_tokens as they expire.

Endpoint Authentication

To authenticate to an endpoint, include an Authorization HTTP header in bearer mode with your access_token. For example:

Authorization: Bearer 2989569f76bffd50735c1c27ad3df57b7b3b409e

You can alternatively supply the access_token as a GET or POST parameter.