Job Results History | Documentation for the Hill Labs API

Description

Use this endpoint to poll for historical test results.

The API returns result data in the standard format by default.

Do not poll more frequently than once every 20 minutes. Hill Labs recommends intervals of 30 to 60 minutes.

Specify dates and times in UTC when you call the endpoint.

Result Summaries

This endpoint returns a paginated list of result summaries.

Endpoint

Testing: GET https://cat-api.hill-laboratories.com/client/api/v4/results?{parameters}

Production: GET https://api.hill-laboratories.com/client/api/v4/results?{parameters}

Headers

The Authorization header is required. The Accept header indicates that you expect a JSON response.

Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

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-laboratories.com/client/api/v4/results?orderId=123456

Parameters

Name	Description
`dateFrom` and `dateTo`	Filter results by when each result was created, shown as `resultCreatedAt` in the result summary. Supply both parameters in UTC to set a date range, or omit both to use the default range of the last three months. The range includes results created at either boundary. Use ISO 8601 timestamps, for example `2023-07-03T12:44:25Z`. Validation rules: `dateFrom` must be earlier than `dateTo`. `dateFrom` must be earlier than the request time. `dateTo` must be earlier than or equal to the request time. `dateTo` must be no more than one year after `dateFrom`.
`orderId`	Filter results for a specific order ID.
`finalOnly`	Return only final results.
`clientReference`	Filter results by the order’s client reference.
`clientOrderNumber`	Filter results by the order’s client order number.
`additionalClientReference`	Filter results by the order’s additional client reference.
`quoteNumber`	Filter results by the order’s quote number.
`limit`	Set the maximum number of result summaries to return per page. Default: 100. Maximum: 200.
`offset`	Set the number of results to skip for pagination. Default: 0.

Response Schema

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

Pagination

Fields in the pagination object.

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)

Result summary

Fields in each item of the results array.

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-065432109876",
      "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

Use this endpoint to retrieve the latest detailed result 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

The Authorization header is required. The Accept header indicates that you expect a JSON response.

Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Example Request

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

Response Schema

Latest result

Fields returned by the latest-result endpoint.

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
`analystComments`	String providing comments on the job from the lab
`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

Order references

Fields in each item of the orderReferences array.

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

Contacts

Fields in each item of the contacts array.

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

Addresses

Fields in each item of the addresses array.

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”)

Samples

Fields in each item of the samples array.

Field Name	Description
`name`	Sample name
`clientSampleId`	An optional identifier allowing assignment of a reference number or code to a sample
`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

Sample type

Fields in the sampleType object.

Field Name	Description
`sampleTypeCode`	Sample type code
`sampleTypeName`	Sample type name

Location

Fields in the location object.

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

Containers

Fields in each item of the containers array.

Field Name	Description
`barcode`	Object containing container barcode details

Barcode

Fields in the barcode object.

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

Analytical tests

Fields in each item of the analyticalTests array.

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

Test results

Fields in each item of the testResults array.

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

Result details

Fields in the result object.

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-065432109876",
  "orderId": 123456,
  "labJobNumber": 123456,
  "isFinal": true,
  "analystComments": "This is an example comment",
  "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

Use this endpoint to retrieve a result by its result ID, including a previous result that has since been superseded.

Endpoint

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

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

Headers

The Authorization header is required. The Accept header indicates that you expect a JSON response.

Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json

Example Request

Get result details by result ID: GET https://api.hill-laboratories.com/client/api/v4/results/6c8b519b-7b00-470b-86b8-065432109876

Response Schema

Same as the above

Example Response

Example Job Polling Result

{
  "resultId": "6c8b519b-7b00-470b-86b8-065432109876",
  "orderId": 123456,
  "labJobNumber": 123456,
  "isFinal": true,
  "analystComments": "This is an example comment",
  "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"
    }
  ]
}