Request / Response

The KPA EHS API follows a simple JSON-RPC style request/response.

The Request

To make a request to the API, send a GET or POST request via HTTPS to the method's URL. The KPA EHS API requires TLS 1.2 (as TLS 1.0 and 1.1 have known vulnerabilities). The URL has this format:


Any time you make a request, you must provide a plain, json-serialized request object. At the very least it will contain a token field (containing your token).

If you wish to make the response JSON more readable, then you may also include a pretty field set to true.

Each method may include additional fields in the request data (such as user):

  "token": "ABCD",
  "pretty": true,
  "user": 99


Each method may be executed via either a GET or POST request.


POST requests should pass the request data's JSON as the body:


GET requests should pass the request data's JSON as the query string:


Because HTTP has several reserved characters. You may need to encode your JSON using something like encodeURIComponent :

Note: PowerBi, Postman and Chrome already handle this this encoding for you.


The Response

The response will always be a JSON object with an ok field set to either true or false.


If an error occurs, then ok will be false. There will be an error field which contains a error identifier. In some cases, there will also be a description field with an explanation.

  "ok": false,
  "error": "invalid_token",
  "description": "The token `TEST_TOKEN` was not found."

If the request succeeds, then ok will be true. Depending on the method, other properties will be included in the response.

  "ok": true,
  "user": {
    "id": "ABCD",
    "name": "John Sample"

NOTE: Keep in mind that if a request does not reach the API (or the response does not reach your application) then the error message provided by your ISP, etc will likely not be JSON object with the given format.

Response Code

All responses will always have a status code of 200 (OK). This includes error responses.

Response Headers

All requests to the API will also include the following response headers:

Response Header Example Description
HZS-Request-ID DA234C08AF6F An alpha-numeric ID assigned to this specific request. Can be used for debugging request with tech support.
HZS-Response-Time 28 How long the server took to process the request (in ms).