Job Results History

Description

This service allows onboarded customers to Poll our API for historical test results.

By default, result data is provided in a standard format.

Maximum permitted polling is 20 minutes, we recommend you only poll in 30-60 minutes intervals.

A UTC date/time is specified in the endpoint call.

Result Summaries

This will return a paginated list of Result Summaries.

Endpoint

Testing: GET https://cat-api.hill-laboratories.com/client/api/v4/results

Production: GET https://api.hill-laboratories.com/client/api/v4/results

Headers

Header Name	Value
Content-Type	application/json
Accept	application/json
Authorization	Bearer <Bearer Token>
Accept-Encoding	gzip, deflate, br

Example Requests

Date Range Filtering: GET https://api.hill-laboratories.com/client/api/v4/results?dateFrom=2023-07-03T12:44:25Z&dateTo=2023-07-04T12:44:25Z&limit=5
Filter by Order ID: GET https://api.hill-aboratories.com/client/api/v4/results?orderId=123456

Optional Parameters

Name	Description
dateFrom & dateTo	Filter the results returned using a date range of the result’s reported date.Both must be supplied to enable date range filtering.Dates are in ISO-8601 format, expected in UCT time (e.g. 2023-07-03T12:44:25Z).The following valifation rules apply:dateFrom must be less than dateTodateFrom must be less than the request timedateTo must be less than or equal to the request timedateTo cannot be more than 1 year greater than dateFrom
orderId	Filters the results returned by a specific orderId.
finalOnly	Filters to only return final results.
clientReference	Filters the results returned by the Order’s Client Reference.
clientOrderNumber	Filters the results returned by the Order’s Client Order Number.
additionalClientReference	Filters the results returned by the Order’s Additional Client Reference.
quoteNumber	Filters the results by the Order’s Quote Number.
limit	Used for pagination, the maximum number of result summary to return per page.Default is 100. Maximum is 200.
offset	Used for pagination, the number of items to skip.Default is 0.

Response Schema

Field Name	Description
pagination	Object containing pagination details for the results
results	Array of result objects containing information about each result

Each “pagination” object has the following fields:

Field Name	Description
limit	Number of results returned per page
offset	Offset for pagination
total	Total number of results available (before applying pagination, i.e. can be > 200)
next	Link to the next page of results (null if there is no next page)
prev	Link to the previous page of results (null if there is no prev page)

Each “results” object has the following fields:

Field Name	Description
resultId	Unique identifier for the result
orderId	Unique identifier for the order
labJobNumber	Unique identifier for the lab job
numberOfSamples	Number of samples associated with the result
isFinal	Boolean indicating if the result is final
clientReference	Reference string for the client
additionalClientReference	Additional reference string for the client
quoteNumber	Quote number associated with the order
clientOrderNumber	Client’s order number
primary	Primary contact name associated with the order
submitter	Submitter contact name associated with the order
chargeTo	Charge to information associated with the order
client	Client information associated with the order
resultCreatedAt	Date and time when the result was created
jobRegisteredAt	Date and time when the job was registered

Example Responses

Example Job Polling Result

{
  "pagination": {
    "limit": 5,
    "offset": 0,
    "total": 500,
    "next": "https://api.hill-laboratories.com/client/api/v4/results?dateFrom=2023-07-03T12:44:25Z&dateTo=2023-07-04T12:44:25Z&offset=1&limit=5",
    "prev": null
  },
  "results": [
    {
      "resultId": "6c8b519b-7b00-470b-86b8-06543",
      "orderId": 123456,
      "labJobNumber": 123456,
      "numberOfSamples": 1,
      "isFinal": true,
      "clientReference": "Client Reference",
      "additionalClientReference": "Additional Client Reference",
      "quoteNumber": 123455,
      "clientOrderNumber": "Client Order Number",
      "primary": "Primary Contact",
      "submitter": "Submitter",
      "chargeTo": "Charge to",
      "client": "Client",
      "resultCreatedAt": "2023-07-03T13:36:44Z",
      "jobRegisteredAt": "2023-07-01T13:36:44Z"
    },
    {
      "resultId": "2e3d29b3-1c5c-4147-aa76-e59ccddd4572",
      "orderId": 123456,
      "labJobNumber": 123456,
      "numberOfSamples": 5,
      "isFinal": true,
      "clientReference": "Client Reference",
      "additionalClientReference": "Additional Client Reference",
      "quoteNumber": 123455,
      "clientOrderNumber": "Client Order Number",
      "primary": "Primary Contact",
      "submitter": "Submitter",
      "chargeTo": "Charge to",
      "client": "Client",
      "resultCreatedAt": "2023-07-03T13:11:44Z",
      "jobRegisteredAt": "2023-07-01T13:36:44Z"
    },
    {
      "resultId": "7bf91e39-45ca-46ec-9f91-b016e30dd265",
      "orderId": 123456,
      "labJobNumber": 123456,
      "numberOfSamples": 8,
      "isFinal": false,
      "clientReference": "Client Reference",
      "additionalClientReference": "Additional Client Reference",
      "quoteNumber": 123455,
      "clientOrderNumber": "Client Order Number",
      "primary": "Primary Contact",
      "submitter": "Submitter",
      "chargeTo": "Charge to",
      "client": "Client",
      "resultCreatedAt": "2023-07-03T13:09:44Z",
      "jobRegisteredAt": "2023-07-01T13:36:44Z"
    },
    {
      "resultId": "4bfb9abf-7516-434e-bbaa-9cce637d6ed7",
      "orderId": 123456,
      "labJobNumber": 123456,
      "numberOfSamples": 1,
      "isFinal": true,
      "clientReference": "Client Reference",
      "additionalClientReference": "Additional Client Reference",
      "quoteNumber": 123455,
      "clientOrderNumber": "Client Order Number",
      "primary": "Primary Contact",
      "submitter": "Submitter",
      "chargeTo": "Charge to",
      "client": "Client",
      "resultCreatedAt": "2023-07-03T13:02:44Z",
      "jobRegisteredAt": "2023-07-01T13:36:44Z"
    },
    {
      "resultId": "93c92aaa-5906-43b5-8488-47896274312f",
      "orderId": 123456,
      "labJobNumber": 123456,
      "numberOfSamples": 9,
      "isFinal": true,
      "clientReference": "Client Reference",
      "additionalClientReference": "Additional Client Reference",
      "quoteNumber": 123455,
      "clientOrderNumber": "Client Order Number",
      "primary": "Primary Contact",
      "submitter": "Submitter",
      "chargeTo": "Charge to",
      "client": "Client",
      "resultCreatedAt": "2023-07-03T12:50:44Z",
      "jobRegisteredAt": "2023-07-01T13:36:44Z"
    }
  ]
}

Latest Result by Lab Job Number

This will return the latest detailed results for a job.

Endpoint

Testing: GET https://cat-api.hill-laboratories.com/client/api/v4/jobs/{labJobNumber}/latest-result

Production: GET https://api.hill-laboratories.com/client/api/v4/jobs/{labJobNumber}/latest-result

Headers

Header Name	Value
Content-Type	application/json
Accept	application/json
Authorization	Bearer <Bearer Token>
Accept-Encoding	gzip, deflate, br

Example Request

Get the latest result for Job 123456: GET https://api.hill-laboratories.com/client/api/v4/jobs/123456/latest-result

Response Schema

Field Name	Description
resultId	Unique identifier for the result
orderId	Unique identifier for the order
labJobNumber	Unique identifier for the lab job
isFinal	Boolean indicating if the result is final
jobReceivedAt	Date and time when the job was received
jobRegisteredAt	Date and time when the job was registered
jobFinishedAt	Date and time when the job was finished
resultCreatedAt	Date and time when the result was created
clientReference	Reference string for the client
additionalClientReference	Additional reference string for the client
quoteNumber	Quote number associated with the order
clientOrderNumber	Client’s order number
orderReferences	Array of custom order reference objects
contacts	Array of contact objects related to the order
addresses	Array of address objects related to the order
notes	Notes associated with the job/order
samples	Array of sample objects related to the order
analyticalTestDefinitions	Array of analytical test definition objects

Each “orderReferences” object has the following fields:

Field Name	Description
name	Name of the custom reference
value	Value of the custom reference

Each “contacts” object has the following fields:

Field Name	Description
hillLabsContactId	The unique ID for the contact
name	Name of the contact
email	Email address of the contact
orderRoles	Array of order roles associated with the contact

Each “addresses” object has the following fields:

Field Name	Description
recipient	Recipient name (nullable)
address1	Address line 1
address2	Address line 2
city	City
region	Region or state (nullable)
country	Country
postCode	Postal code
orderRoles	Array of order roles associated with the address (roles are “INVOICE” or “DELIVERY”)

Each “samples” object has the following fields:

Field Name	Description
name	Sample name
sequence	Sequence number of the sample
sampleType	Object containing sample type information
location	Object containing location information
containers	Array of container objects related to the sample
analyticalTests	Array of analytical test objects related to sample
testResults	Array of test result objects related to sample

Each “sampleType” object has the following fields:

Field Name	Description
sampleTypeCode	Sample type code
sampleTypeName	Sample type name

Each “location” object has the following fields:

Field Name	Description
intersect	Array of objects containing latitude and longitude coordinates
name	Name of the location (nullable)

Each “containers” object has the following fields:

Field Name	Description
barcode	Object containing container barcode details

Each “barcode” object has the following fields:

Field Name	Description
value	Value of the container barcode
type	Type of the container barcode (e.g. LINEAR)

Each “analyticalTests” object has the following fields:

Field Name	Description
code	Code of the analytical test
name	Name of the analytical test

Each “testResults” object has the following fields:

Field Name	Description
status	Status of the test result (e.g. IN_PROGRESS, COMPLETE)
completedAt	Date and time when the test was completed
measurandCode	Code of the measurand (analyte)
measurandName	Name of the measurand (analyte)
result	Object containing test result details

Each “result” object has the following fields:

Field Name	Description
unitOfMeasure	Unit of measurement for the result
detectionLimit	Detection limit of the result
formattedDetectionLimit	Formatted detection limit of the result
upperLimit	Upper limit of the result
rangeIndicator	Indicator if the result is above or below the limit
numericResult	Numeric value of the result
formattedResult	Formatted representation of the result

Example Response

Example Job Polling Result

{
  "resultId": "6c8b519b-7b00-470b-86b8-06543",
  "orderId": 123456,
  "labJobNumber": 123456,
  "isFinal": true,
  "jobReceivedAt": "2023-07-20T03:04:05.412000+00:00",
  "jobRegisteredAt": "2023-07-20T03:05:36.787000+00:00",
  "jobFinishedAt": "2023-07-20T04:00:01.454000+00:00",
  "resultCreatedAt": "2023-07-20T20:05:43.873+00:00",
  "clientReference": "Example Client Reference",
  "additionalClientReference": "Example  Client Reference",
  "quoteNumber": 123455,
  "clientOrderNumber": "Example Client Order Number",
  "orderReferences": [
    {
      "name": "Example Custom Reference 1",
      "value": "Reference Value"
    },
    {
      "name": "Example Custom Reference 2",
      "value": "Reference Value"
    }
  ],
  "contacts": [
    {
      "hillLabsContactId": "0e529040-52d4-4878-85d1-4d503b4f9f24",
      "name": "Test",
      "orderRoles": [
        "CHARGE_TO",
        "CLIENT"
      ]
    },
    {
      "hillLabsContactId": "e3cb05ec-a088-4f9b-b50f-510c5426cf47",
      "name": "Test",
      "email": "testemail@hill-labs.co.nz",
      "orderRoles": [
        "PRIMARY",
        "SUBMITTER"
      ]
    }
  ],
  "addresses": [
    {
      "recipient": null,
      "address1": "28 Duke Street",
      "address2": "Frankton",
      "city": "Hamilton",
      "region": "",
      "country": "New Zealand",
      "postCode": "3204",
      "orderRoles": [
        "INVOICE"
      ]
    }
  ],
  "notes": "Some notes for the job/order",
  "samples": [
    {
      "name": "Sample 1",
      "sequence": 1,
      "sampleType": {
        "sampleTypeCode": "HoneyD",
        "sampleTypeName": "Honey"
      },
      "location": {
        "intersect": [
          {
            "longitude": 168.407300001865,
            "latitude": -46.0494999997713
          }
        ],
        "name": "Location name"
      },
      "containers": [
        {
          "barcode": {
            "value": "331001455044",
            "type": "LINEAR"
          }
        }
      ],
      "analyticalTests": [
        {
          "code": "Honey3in1"
        },
        {
          "code": "Honey_Forecast_withNPA"
        }
      ],
      "testResults": [
        {
          "status": "COMPLETE",
          "completedAt": "2023-07-20T03:56:53.194Z",
          "measurandCode": "Fmgo_20_max_weeks",
          "measurandName": "Forecasted Weeks to Maximum Methylglyoxal at 20°C",
          "result": {
            "unitOfMeasure": "weeks",
            "detectionLimit": 1,
            "formattedDetectionLimit": "1",
            "upperLimit": 104,
            "rangeIndicator": "ABOVE_UPPER_LIMIT",
            "numericResult": 214.428571428571,
            "formattedResult": "> 104"
          }
        },
        {
          "status": "COMPLETE",
          "completedAt": "2023-07-20T03:56:53.236Z",
          "measurandCode": "Fmgo_27_max_weeks",
          "measurandName": "Forecasted Weeks to Maximum Methylglyoxal at 27°C",
          "result": {
            "unitOfMeasure": "weeks",
            "detectionLimit": 1,
            "formattedDetectionLimit": "1",
            "upperLimit": 104,
            "rangeIndicator": "BETWEEN_LIMITS",
            "numericResult": 82.7142857142857,
            "formattedResult": "83"
          }
        },
        {
          "status": "COMPLETE",
          "completedAt": "2023-07-20T03:09:50.926Z",
          "measurandCode": "mgo_mgkg_ar_calc",
          "measurandName": "Methylglyoxal (MGO)",
          "result": {
            "unitOfMeasure": "mg/kg",
            "detectionLimit": 5,
            "formattedDetectionLimit": "5",
            "rangeIndicator": "BETWEEN_LIMITS",
            "numericResult": 658.22033149,
            "formattedResult": "658"
          }
        }
      ]
    }
  ],
  "analyticalTestDefinitions": [
    {
      "code": "Honey3in1",
      "name": "3 in 1 Honey Suite"
    },
    {
      "code": "Honey_Forecast_withNPA",
      "name": "Honey Forecast with NPA"
    }
  ]
}

Result by Result ID

This will return a result by its Result ID. This is useful for retrieving previous results that have been superseded.

Endpoint

Testing: GET https://cat-api.hill-laboratories.com/client/api/v4/result/{resultId}

Production: GET https://api.hill-laboratories.com/client/api/v4/result/{resultId}

Headers

Header Name	Value
Content-Type	application/json
Accept	application/json
Authorization	Bearer <Bearer Token>
Accept-Encoding	gzip, deflate, br

Example Request

Get the latest result for Job 123456: GET https://api.hill-laboratories.com/client/api/v4/results/6c8b519b-7b00-470b-86b8-06543

Response Schema

Same as the above

Example Response

Example Job Polling Result

{
  "resultId": "6c8b519b-7b00-470b-86b8-06543",
  "orderId": 123456,
  "labJobNumber": 123456,
  "isFinal": true,
  "jobReceivedAt": "2023-07-20T03:04:05.412000+00:00",
  "jobRegisteredAt": "2023-07-20T03:05:36.787000+00:00",
  "jobFinishedAt": "2023-07-20T04:00:01.454000+00:00",
  "resultCreatedAt": "2023-07-20T20:05:43.873+00:00",
  "clientReference": "Client Reference",
  "additionalClientReference": "Client Reference",
  "quoteNumber": 123455,
  "clientOrderNumber": "Client Order Number",
  "orderReferences": [
    {
      "name": "Example Custom Reference 1",
      "value": "Reference Value"
    },
    {
      "name": "Example Custom Reference 2",
      "value": "Reference Value"
    }
  ],
  "contacts": [
    {
      "hillLabsContactId": "0e529040-52d4-4878-85d1-4d503b4f9f24",
      "name": "Test",
      "orderRoles": [
        "CHARGE_TO",
        "CLIENT"
      ]
    },
    {
      "hillLabsContactId": "e3cb05ec-a088-4f9b-b50f-510c5426cf47",
      "name": "Test",
      "email": "jon.harris@hill-labs.co.nz",
      "orderRoles": [
        "PRIMARY",
        "SUBMITTER"
      ]
    }
  ],
  "addresses": [
    {
      "recipient": null,
      "address1": "28 Duke Street",
      "address2": "Frankton",
      "city": "Hamilton",
      "region": "",
      "country": "New Zealand",
      "postCode": "3204",
      "orderRoles": [
        "INVOICE"
      ]
    }
  ],
  "notes": "Some notes for the job/order",
  "samples": [
    {
      "name": "Sample 1",
      "sequence": 1,
      "sampleType": {
        "sampleTypeCode": "HoneyD",
        "sampleTypeName": "Honey"
      },
      "location": {
        "intersect": [
          {
            "longitude":,
            "latitude":
          }
        ],
        "name": "Location name"
      },
      "containers": [
        {
          "barcode": {
            "value": "331001455044",
            "type": "LINEAR"
          }
        }
      ],
      "analyticalTests": [
        {
          "code": "Honey3in1"
        },
        {
          "code": "Honey_Forecast_withNPA"
        }
      ],
      "testResults": [
        {
          "status": "COMPLETE",
          "completedAt": "2023-07-20T03:56:53.194Z",
          "measurandCode": "Fmgo_20_max_weeks",
          "measurandName": "Forecasted Weeks to Maximum Methylglyoxal at 20°C",
          "result": {
            "unitOfMeasure": "weeks",
            "detectionLimit": 1,
            "formattedDetectionLimit": "1",
            "upperLimit": 104,
            "rangeIndicator": "ABOVE_UPPER_LIMIT",
            "numericResult": 214.428571428571,
            "formattedResult": "> 104"
          }
        },
        {
          "status": "COMPLETE",
          "completedAt": "2023-07-20T03:56:53.236Z",
          "measurandCode": "Fmgo_27_max_weeks",
          "measurandName": "Forecasted Weeks to Maximum Methylglyoxal at 27°C",
          "result": {
            "unitOfMeasure": "weeks",
            "detectionLimit": 1,
            "formattedDetectionLimit": "1",
            "upperLimit": 104,
            "rangeIndicator": "BETWEEN_LIMITS",
            "numericResult": 82.7142857142857,
            "formattedResult": "83"
          }
        },
        {
          "status": "COMPLETE",
          "completedAt": "2023-07-20T03:09:50.926Z",
          "measurandCode": "mgo_mgkg_ar_calc",
          "measurandName": "Methylglyoxal (MGO)",
          "result": {
            "unitOfMeasure": "mg/kg",
            "detectionLimit": 5,
            "formattedDetectionLimit": "5",
            "rangeIndicator": "BETWEEN_LIMITS",
            "numericResult": 658.22033149,
            "formattedResult": "658"
          }
        }
      ]
    }
  ],
  "analyticalTestDefinitions": [
    {
      "code": "Honey3in1",
      "name": "3 in 1 Honey Suite"
    },
    {
      "code": "Honey_Forecast_withNPA",
      "name": "Honey Forecast with NPA"
    }
  ]
}