IHD LabFlow (2.29.1)

Download OpenAPI specification:Download

An API for managing orders with Innovative Health Diagnostics.

Introduction

The LabFlow API offers diagnostics-as-a-service features to its partners.

Partner Workflows

There are many different varieties of workflows that are enabled by the LabFlow API, which are customized based on the specific needs of the partner.

In scenarios where IHDLab will be handling the process of fulfilling patient kit orders, the partner's workflow will begin with a Kit Order.
In scenarios where the partner will provide the kit to the patient through other means, the partner's workflow will begin with a Lab Order.

Authentication

The LabFlow API offers a single authentication mechanism: API keys. API keys are generated on a per-organization basis and are used to authenticate requests to the API. API keys are passed in the x-api-key header.

Active partners will be provided with an admin portal to manage its own keys. Contact daas.support@ihdlab.com to request access to the portal or require a staging key for testing.

Code Samples

IHD provides a sample application to illustrate common interactions with the API later.

Common Questions

Q: How do I get my API key?

A: As part of partner onboarding, you will be provided with a One-Time Token URL, that can be consumed via a webbrowser or an API platform built for calling REST APIs. The response payload will contain the API key that can be used for your calls. Once the token is consumed, it will no longer be available and subsequent calls will receive a 404 error.

If you are using a browser with plugins, the URL may be consumed by one of the plugins, returning a 404 error, therefore we recommend using a neutral browser profile or a tool like Postman/Insomnia.

Q: Why do the mocked results look different than I'd expect?

A: Every partner's panel configuration is different, so there will be differences with the results and rejections returned. We can provide a customized mock after the original kit is configured by the lab, but until then, a more generic mock will be returned that demonstrates the keys and sample values in the payload.

Q: Why do the mocked results look different than I'd expect?

A: Every partner's panel configuration is different, so there will be differences with the results and rejections returned. We can provide a customized mock after the original kit is configured by the lab, but until then, a more generic mock will be returned that demonstrates the keys and sample values in the payload.

Kit

Operations for viewing kits

Get All Kits

Get all of the active configured kits and their associated details

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Kit by ID

Get a specific kit and its details by kit ID

Authorizations:
apiKey
path Parameters
id
required
string

Unique identifier for a kit

Responses

Response samples

Content type
application/json
{
  • "kidId": "kit-d3544371-6b8e-4dfb-a604-55e07b962d13",
  • "panelId": "000999",
  • "externalId": "PRTNR-00001",
  • "name": "Partner Kit #1",
  • "description": "A kit containing a specific test"
}

Order

Operations for handling kit and lab orders

Get Orders

Get all orders for the organization

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Orders V2

Get all orders for the organization with support for pagination and query param based filter support

Authorizations:
apiKey
query Parameters
orderNo
string

Returns orders that have the specified Order No.

email
string <email>

Returns orders that have the specified email as customer email within order.

registrationCode
string

Returns orders that have the specified Registration Code.

orderType
string
Enum: "KIT" "LAB"

Returns orders that have the specified Order Type.

orderStatus
string
Enum: "NEW" "PENDING_DELIVERY" "IN_TRANSIT" "OUT_FOR_DELIVERY" "DELIVERED" "DELIVERED_TO_PARTNER" "DELIVERY_FAILED" "DELIVERY_ERROR" "CANCELATION_REQUESTED" "CANCELLED" "REGISTERED" "RECEIVED" "PROCESSING" "RESULTED"

Returns orders that have the specified Order Status.

kitId
string

Returns orders that are created using the specified Kit Id, should follow kit-0c05f7a3-4056-4ce8-a738-b8b19bab619c format

externalId
string

Returns orders that have the specified External Id.

shipmentTrackingCode
string

Returns orders that have the specified Shipment Tracking Code.

returnShipmentTrackingCode
string

Returns orders that have the specified Return Shipment Tracking Code.

sortBy
string
Enum: "dateCreated" "dateLastUpdated"

Sort the responses by a set value.

sortDir
string
Enum: "asc" "desc"

Sets the direction of the sort order.

page
integer

Page number. If not provided defaults to 1.

pageSize
integer

Page size. If not provided defaults to 10.

dateCreatedStart
string <date-time>

Returns orders created on or after the specified dateCreated. Should follow ISO 8601 format as 2023-06-10T00:00:00.000Z

dateCreatedEnd
string <date-time>

Returns orders created on or before the specified dateCreated. Should follow ISO 8601 format as 2023-06-10T00:00:00.000Z

dateRegisteredStart
string <date-time>

Returns orders registered on or after the specified dateRegistered. Should follow ISO 8601 format as 2023-06-10T00:00:00.000Z

dateRegisteredEnd
string <date-time>

Returns orders registered on or before the specified dateRegistered. Should follow ISO 8601 format as 2023-06-10T00:00:00.000Z

dateCanceledStart
string <date-time>

Returns orders canceled on or after the specified dateCanceled. Should follow ISO 8601 format as 2023-06-10T00:00:00.000Z

dateCanceledEnd
string <date-time>

Returns orders canceled on or before the specified dateCanceled. Should follow ISO 8601 format as 2023-06-10T00:00:00.000Z

dateCollectedStart
string <date-time>

Returns orders collected on or after the specified dateCollected. Should follow ISO 8601 format as 2023-06-10T00:00:00.000Z

dateCollectedEnd
string <date-time>

Returns orders collected on or before the specified dateCollected. Should follow ISO 8601 format as 2023-06-10T00:00:00.000Z

dateResultedStart
string <date-time>

Returns orders resulted on or after the specified dateResulted. Should follow ISO 8601 format as 2023-06-10T00:00:00.000Z

dateResultedEnd
string <date-time>

Returns orders resulted on or before the specified dateResulted. Should follow ISO 8601 format as 2023-06-10T00:00:00.000Z

dateLastUpdatedStart
string <date-time>

Returns orders last updated on or after the specified dateLastUpdated. Should follow ISO 8601 format as 2023-06-10T00:00:00.000Z

dateLastUpdatedEnd
string <date-time>

Returns orders last updated on or before the specified dateLastUpdated. Should follow ISO 8601 format as 2023-06-10T00:00:00.000Z

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pagination": {
    }
}

Get Order by ID

Get a specific order by its order ID

Authorizations:
apiKey
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "order-8655eb89-0b28-44f2-9e2b-5779cf5730b7",
  • "status": "NEW",
  • "org": {
    },
  • "kit": {
    },
  • "accession": {
    }
}

Cancel Order by ID

Cancel an order by its order ID

Authorizations:
apiKey
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Create Kit Order

Create an order for a kit

Authorizations:
apiKey
Request Body schema: application/json
required
kitId
required
string [ 1 .. 50 ] characters
required
object

Responses

Request samples

Content type
application/json
{
  • "kitId": "kit-d3544371-6b8e-4dfb-a604-55e07b962d13",
  • "customer": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "success": true,
  • "error": "Error message"
}

Register Kit

Register a kit that has been received by a customer. This will trigger the order to be sent to the lab.

Authorizations:
apiKey
query Parameters
test
string

Instantly populates mock order results when set to true.

Note: Only valid in the staging environment. Will return an error in production.

testType
string
Enum: "RECEIVED" "REJECTED" "RESULTED"

Works when coupled with test; the type of results to populate.

Note: Only valid in the staging environment. Will return an error in production.

Request Body schema: application/json
required
registrationCode
required
string
required
object

Responses

Request samples

Content type
application/json
{
  • "registrationCode": "string",
  • "patient": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "success": true,
  • "error": "Error message"
}

Create Lab Order

Create a lab order directly

Authorizations:
apiKey
query Parameters
test
string

Instantly populates mock order results when set to true Only valid in the staging environment.

Note: Only valid in the staging environment. Will return an error in production.

testType
string
Enum: "RECEIVED" "REJECTED" "RESULTED"

Works when coupled with test; the type of results to populate.

Note: Only valid in the staging environment. Will return an error in production.

Request Body schema: application/json
required
kitId
required
string
externalId
string

An id managed by the partner for this specific object type

dateRegistered
string <date-time> ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$
required
object

Responses

Request samples

Content type
application/json
{
  • "kitId": "string",
  • "externalId": "string",
  • "dateRegistered": "2023-01-01T11:11:11Z",
  • "patient": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "success": true,
  • "error": "Error message"
}

Inbox

The inbox provides a mechanism for surfacing updates to orders that are deemed relevant to the partner.

The inbox should be checked between 30 and 60 minutes for the most current results.

Get Inbox

Get all order ids that need attention from the inbox.

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Clear the Inbox

Remove all orders from the inbox (does not affect the orders themselves)

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Delete an Inbox Order by ID

Clear an order from the inbox by its order Id. This does not affect the order itself.

Authorizations:
apiKey
path Parameters
id
required
string

Order ID

Responses

Response samples

Content type
application/json
{
  • "success": true
}