Support

Our support team will be able to help you out with at any stage. You can email us at cx@hill-labs.co.nz

Introduction

An API (Application Programming Interface) is a set of functions and procedures that allow easy access to a select set of data hosted in a third-party system/s, in this case Hill Laboratories’ systems.

Our API allows programmatic access to areas such as pre-registered jobs, job results and job history. The benefits identified so far are:

• Creating pre-registered jobs in seconds, removing the need for paper registration.
  • No human error transcribing. No jobs on hold whilst we confirm the tests on samples.
  • Speedy submission of samples
  • Easy identification of samples
• Receiving results directly into your systems seconds after they are approved.
  • No manual entry of data
  • No mis-keyed data entry
  • Ability to search for historical results

Purpose

This document outlines the overall onboarding process required to integrate with and utilise the Hill Laboratories Limbus API. It is intended for Hill Laboratories’ customers only. It describes what you need to do, what technical skill sets will be required and what process we will go through in order to help you establish API connectivity.

We’ve all used API’s before in which loose documentation is handed over, and developers progress via trial and error. This can be time consuming, expensive and doesn’t deliver the full potential of the solution. We aim to provide enough documentation so that you can progress, but we also want to be available to help should you have any queries. This document will outline the process, timeline and support points. 

Technical Requirements

The API is based on a number of secured REST endpoints. Your development team will need to have the understanding or capability to:

• Construct JSON documents to submit and request data
• Understand authentication using JWT tokens.
• Understand REST in particular POST and GET requests
• Be able to construct an endpoint that will accept a pre-arranged data payload.

REST endpoints are ubiquitous and provide a universal data transfer mechanism. Therefore we are not restricted to a single development language. As long as your language of choice supports REST over HTTPS, then you will be able to interface with the API.

Limitations

Currently, our API is not all-encompassing, and so may not meet your needs at the moment. Rest assured we are working on all of the points below. If you are impacted by these, please stay in touch with our helpdesk, and they’ll inform you when you will be able to begin onboarding. Currently, we are unable to support the following:

Job submission where the Job is not charged to the submitting Organisation	We only accept orders where your organisation is going to be paying the invoice. We do not support your organisation submitting the order and expecting that another person/organisation will pay the invoice.
Mapping to your custom codes, e.g. Analytical Tests, Analytes	You must use our test and analyte codes. We do not support you submitting data using your organisation’s codes requiring us to translate to our codes.

Time Line (2-6 weeks)

The integration can be completed in as little as two weeks.

We are confident that the process can be completed in 2 to 6 weeks. The time to completion will really depend on your priorities and your development team. We will help get you started (initialisation phase) and help with the Go-Live. The development (integration phase) can be as long or as short as you like.

Initial Discussion

Before we kick off the integration, we’d like to set up a quick meeting. The meeting will seek to confirm:

• What part of the API you plan to use.
• How you wish to authenticate, as a direct client or placing orders on behalf of customers 
• Whether you are impacted by our current restrictions, and if so, can we work around them or wait until the feature is complete (we can discuss our projected implementation timeline at this point).
• Your team’s technical capability.
• What Analytical Tests you want to submit. We may need to expose some of your selected tests to our API.

If you decide that you’d like to proceed, then we’ll set up a kick-off meeting with your development lead.

Integration Phase

The integration phase is where you begin your development. We’ll set up a kick-off meeting in which we’ll provide you with:

• Technical documentation.
• Access to retrieve JWT tokens to a development environment.
• Applicable example Sample and Analytical Test codes you can use in your requests.
• Appropriate Organisation details set up in our development environment. 
• Contact details for developer help.
  

The development environment will be isolated from all other systems. You can’t do any damage, so feel free to play around and get comfortable.

When you believe you have completed your development, then you should reach out to your support contact. They will set you up in an acceptance testing environment. This gives us both an environment in which we can perform end to end testing. The process will involve some manual intervention as we’ll need to fake the data through the lab and generate your required results. Once we are both comfortable that the integration is working as intended, then we’ll move on to Go-Live.

Integration Testing

The Help Desk will coordinate integration testing with your development lead/IT department. The tasks for validation should follow the guidelines below : 

• A valid Auth0 token provided for access to the integration testing environment
• Successful submission of 10 job requests that contain standard tests that you use.
• Successful distribution of the 10 generated results to your endpoint. We’ll check our logs for 500 errors.

Go-Live

When we have both agreed that testing is complete, then we can move onto the final phase; Go Live. The Go Live process will be much the same as the integration testing, excluding the testing. If you’d like our support desk to confirm your first few submissions then give us a call. We’ll be happy to check them out for you.