Find and retrieve results

Outcome

For each customer connection, use its access token to retrieve the results that customer is authorised to view. You can also retrieve result details and request the latest result for a known LabSys job number.

Available operations

1. Request a results page

Use the API base URL for your environment from the onboarding pack.

GET {results_api_base_url}/client/api/v4/results?dateFrom={UTC_START}&dateTo={UTC_END}&limit=100&offset=0
Authorization: Bearer {partner_access_token}
Accept: application/json

Use both dateFrom and dateTo, or omit both. If both are omitted, the API uses the last three months. Dates use UTC, and both range boundaries are inclusive. The maximum date range is one year. The date window applies to when the result was created, as reflected by resultCreatedAt in a result summary.

A summary includes resultId, labJobNumber, orderId, order references, sample count, final status and resultCreatedAt. The API includes the total number of results the customer who approved your app can access through mylab in the pagination block. A job can have more than one result, so use resultId as the unique key.

Filter and page through results

• Use orderId, clientReference, additionalClientReference, clientOrderNumber or quoteNumber to narrow the list.
• Use finalOnly=true to return final results only.
• Use search to match an exact whole value, case-insensitively, in a supported job reference or sample name. Partial matches are not returned.
• The default page size is 100 and the maximum is 200. Use the returned pagination.next link for the next page and pagination.prev for the previous page. These links retain the current filters.
• Use resultId as the unique key for a result. A job can have more than one result.

2. Retrieve result details

Choose a result from the list and use its resultId:

GET {results_api_base_url}/client/api/v4/results/{resultId}
Authorization: Bearer {partner_access_token}
Accept: application/json

Fetch details only for results your application needs to display. Keep the result ID and result-created date to track updates.

3. Get the latest result for a known job

GET {results_api_base_url}/client/api/v4/jobs/{labJobNumber}/latest-result
Authorization: Bearer {partner_access_token}
Accept: application/json

Use this operation when you already have an authorised LabSys job number and need its latest available result.

Polling pattern

1. Choose a UTC date window and request the first page.
2. Follow each pagination.next link until there is no next link.
3. Store or update results by resultId; do not use the job number as the unique result key.
4. Repeat the query using the polling interval and date-window strategy you agreed with Hill Labs for your integration.

Common errors

Next step

Continue to Keep access working.