API docs by Redocly

IHD LabFlow — Partner API v3 (2.27.2)

Download OpenAPI specification:

API version: Partner API v3 (v4 · legacy · all · home)

Overview

LabFlow is IHD’s diagnostics platform for partner integrations. Use REST with your organization API key in the x-api-key header. This reference documents Partner API v3 (default), Partner API v4 (opt-in), and legacy v1/v2 paths.

In this document

Section Jump
Workflows Kit vs lab
v3 vs v4 Versions
Migration v3 → v4
Auth Authentication
v4 models All v4 models

Partner workflows

Scenario Start here
IHD ships kits to patients Create kit order (v3) or v4 kit create
Partner supplies the kit Create lab order (v3) or v4 lab create
Ordering clinician on lab orders List providers (v3) / Practitioners (v4)

Partner API versions

Version Base path Notifications Recommended for
v3 (default) /v3/... Inbox polling (GET /v3/inbox) plus REST Current production integrations
v4 (opt-in) /v4/partner/... HTTPS webhooks and optional GET /v4/partner/events for replay FHIR-aligned payloads and event-driven delivery

The same x-api-key applies to both versions; organization context is shared. Notification state is not shared—v4 does not read v3 inbox flags. Partner API v4 returns 403 with PARTNER_V4_NOT_ENABLED until IHD enables v4 for your organization.

Use the docs home to open v3, v4, legacy, or the combined reference.

Migrating from v3 inbox to v4 webhooks

Today — v3 (poll)

Step Partner LabFlow
1 GET /v3/inbox Returns order ids that need attention
2 GET /v3/orders/{id} Returns full order payload

Target — v4 (push)

Step Partner LabFlow
1 POST /v4/partner/webhooks/endpoints Register HTTPS URL; receive signingSecret once
2 (listen) Signed HTTPS POST (for example order.resulted)
3 (optional) GET /v4/partner/events Replay or reconcile the same event envelopes

Cutover checklist

Step Action
1 Contact your IHD account team to enable Partner API v4.
2 Implement a webhook receiver (verify HMAC and timestamp skew ≤ 5 minutes).
3 Register endpoint(s) under /v4/partner/webhooks/endpoints.
4 Map v3 order JSON to v4 PartnerOrderSummary (FHIR field names).
5 Run v3 inbox and v4 webhooks in parallel until cutover; use GET /events to reconcile gaps.

Authentication

LabFlow authenticates partners with API keys issued per organization. Send the key on every request in the x-api-key header.

Active partners can manage keys in the IHD admin portal. Contact daas.support@ihdlab.com for portal access or a staging key.

Code samples

Reference implementation:

Common questions

Q: How do I get my API key?

A: During onboarding, IHD provides a one-time token URL. Open it once in a browser or REST client; the response contains your API key. After the token is consumed, the URL returns 404. Use a clean browser profile or a tool such as Postman or Insomnia so extensions do not consume the token unintentionally.

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

A: Result and rejection payloads depend on your configured test panel. IHD can tailor staging mocks after your kit is configured; until then, generic sample payloads illustrate field names and structure.

apiKey

Security Scheme Type: API Key
Header parameter name: x-api-key

Inbox

Poll for order identifiers with new partner-relevant activity (for example, results or status changes).

Integrations typically poll on a regular schedule (for example, every 30–60 minutes) in production.

Clear the Inbox (V3)

Clears all order identifiers from the inbox. Underlying orders are unchanged; use after you have processed pending updates.

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
}

Delete an Inbox Order by ID (V3)

Removes one order identifier from the inbox. Does not cancel or modify the order.

Authorizations:
apiKey
path Parameters
id
required
string

Order ID

Responses

Response samples

Content type
application/json
{
}

Get Inbox (V3)

Returns order identifiers currently in your organization's inbox—orders with updates that may require partner action. Pair with GET /v3/order/{id} for full detail.

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
[
]

Get Paginated Inbox (V3)

Returns inbox orders with pagination, sorted by dateLastUpdated descending. Defaults to page 1 with page size 100.

Authorizations:
apiKey
query Parameters
page
integer
Default: 1

Page number. Defaults to 1.

pageSize
integer
Default: 100

Number of orders per page. Defaults to 100.

Responses

Response samples

Content type
application/json
{
}

Kit

Kits configured for your organization—catalog metadata, panels, and fulfillment attributes.

Get All Kits (V3)

Lists active kits configured for your organization, including SKU, panel, and fulfillment details.

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
[
]

Get Kit by ID (V3)

Returns a single kit by LabFlow kit identifier.

Authorizations:
apiKey
path Parameters
id
required
string

Unique identifier for a kit

Responses

Response samples

Content type
application/json
{
}

Order

Create and manage kit and lab orders, retrieve status, register specimens, and cancel when supported.

Cancel Order by ID (V3)

Requests cancellation of an order when the workflow and status allow it.

Authorizations:
apiKey
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
}

Create Kit Order (V3)

Creates a kit fulfillment order (IHD ships collection materials to the patient or recipient).

Authorizations:
apiKey
Request Body schema: application/json
required
kitId
required
string [ 1 .. 50 ] characters
required
object
email
string <email>
firstName
string [ 1 .. 50 ] characters
middleName
string <= 50 characters
lastName
string [ 1 .. 50 ] characters
phone
string
object
object
Array of objects

Optional insurance information for the customer

Array
isPrimary
boolean

Indicates if this is the primary insurance

subscriberId
string

Insurance subscriber ID

relationToInsured
string

Relationship to the insured person

effectiveDate
string <date>

Insurance effective date

firstName
string

First name of the insured

lastName
string

Last name of the insured

dob
string <date>

Date of birth of the insured

groupNumber
string

Insurance group number

insuranceId
string

Insurance provider ID

payorName
string

Name of the insurance payor

object

Optional guarantor information for the patient

firstName
string

First name of the guarantor

lastName
string

Last name of the guarantor

relationship
string

Relationship to the patient. Can be either HL7 code or readable name. Valid HL7 codes are ASC, BRO, CGV, CHD, DEP, DOM, EMC, EME, EMR, EXF, FCH, FND, FTH, GCH, GRD, GRP, MGR, MTH, NCH, NON, OAD, OTH, OWN, PAR, SCH, SEL, SIB, SIS, SPO, TRA, UNK, WRD. Readable names include mother, father, spouse, self, sibling, etc.

dob
string <date>

Date of birth of the guarantor

gender
string
Enum: "M" "F"

Gender of the guarantor

phone
string

Phone number of the guarantor

object

Address of the guarantor

Array of objects

Optional diagnosis information for the order

Array
code
string

Diagnosis code (e.g., ICD-10)

description
string

Description of the diagnosis

system
string

Coding system used (e.g., ICD-10-CM)

type
string
Enum: "A" "F" "W"

Diagnosis type. A = Admitting, F = Final, W = Working

diagnosisDate
string <date>

Date of diagnosis

Responses

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Create Lab Order (V3)

Creates a lab order when your organization supplies the kit or specimen workflow. Include ordering provider details where required.

Authorizations:
apiKey
query Parameters
test
string

Instantly populates mock order results when set to true.

Note: Only valid in the staging environment.

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

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

Note: Only valid in the staging environment.

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
firstName
string
middleName
string
lastName
string
email
string
phone
string
dob
string <date> ^\d{4}-\d{2}-\d{2}$
gender
string
Enum: "Male" "Female" "Unknown"
object
Array of objects

Optional insurance information for the patient

Array
isPrimary
boolean

Indicates if this is the primary insurance

subscriberId
string

Insurance subscriber ID

relationToInsured
string

Relationship to the insured person

effectiveDate
string <date>

Insurance effective date

firstName
string

First name of the insured

lastName
string

Last name of the insured

dob
string <date>

Date of birth of the insured

groupNumber
string

Insurance group number

insuranceId
string

Insurance provider ID

payorName
string

Name of the insurance payor

object

Optional guarantor information for the patient

firstName
string

First name of the guarantor

lastName
string

Last name of the guarantor

relationship
string

Relationship to the patient. Can be either HL7 code or readable name. Valid HL7 codes are ASC, BRO, CGV, CHD, DEP, DOM, EMC, EME, EMR, EXF, FCH, FND, FTH, GCH, GRD, GRP, MGR, MTH, NCH, NON, OAD, OTH, OWN, PAR, SCH, SEL, SIB, SIS, SPO, TRA, UNK, WRD. Readable names include mother, father, spouse, self, sibling, etc.

dob
string <date>

Date of birth of the guarantor

gender
string
Enum: "M" "F" "U"

Gender of the guarantor (M=Male, F=Female, U=Unknown)

phone
string

Phone number of the guarantor

object

Address of the guarantor

Array of objects

Optional diagnosis information for the order

Array
code
string

Diagnosis code (e.g., ICD-10)

description
string

Description of the diagnosis

system
string

Coding system used (e.g., ICD-10-CM)

type
string
Enum: "A" "F" "W"

Diagnosis type. A = Admitting, F = Final, W = Working

diagnosisDate
string <date>

Date of diagnosis

object (OrderingProvider)
npi
required
string^[0-9]{10}$

Entity Type 1 NPI

first_name
required
string [ 1 .. 255 ] characters
middle_name
string [ 1 .. 255 ] characters
last_name
required
string [ 1 .. 255 ] characters
suffix
string [ 1 .. 50 ] characters
credential
string [ 1 .. 20 ] characters
external_provider_id
string [ 1 .. 255 ] characters

Partner-network provider ID (e.g. PWN provider ID). Scoped uniqueness per system + org.

provider_authorized_at
string <date-time>

When the provider authorized this order. ISO 8601 with timezone. Must not be more than 7 days in the future. Defaults to order creation time if not provided.

Responses

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Get Order by ID (V3)

Returns the full order record for a LabFlow order identifier.

Authorizations:
apiKey
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
}

Get Orders V3

Lists orders for your organization with optional filters and pagination.

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 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. Defaults to 1.

pageSize
integer

Page size. Defaults to 10.

dateCreatedStart
string <date-time>

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

dateCreatedEnd
string <date-time>

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

dateRegisteredStart
string <date-time>

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

dateRegisteredEnd
string <date-time>

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

dateCanceledStart
string <date-time>

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

dateCanceledEnd
string <date-time>

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

dateCollectedStart
string <date-time>

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

dateCollectedEnd
string <date-time>

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

dateResultedStart
string <date-time>

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

dateResultedEnd
string <date-time>

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

dateLastUpdatedStart
string <date-time>

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

dateLastUpdatedEnd
string <date-time>

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

Responses

Response samples

Content type
application/json
{
}

Register Kit (V3)

Records patient kit registration or specimen receipt and advances eligible orders toward laboratory processing.

Authorizations:
apiKey
query Parameters
override
boolean

Use true to override the patient details of already registered orders. This will not update order status.

test
string

Instantly populates mock order results when set to true.

Note: Only valid in the staging environment.

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

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

Note: Only valid in the staging environment.

Request Body schema: application/json
required
registrationCode
required
string
required
object
firstName
string
middleName
string
lastName
string
email
string
phone
string
dob
string <date> ^\d{4}-\d{2}-\d{2}$
gender
string
Enum: "Male" "Female" "Unknown"
object
Array of objects

Optional insurance information for the patient

Array
isPrimary
boolean

Indicates if this is the primary insurance

subscriberId
string

Insurance subscriber ID

relationToInsured
string

Relationship to the insured person

effectiveDate
string <date>

Insurance effective date

firstName
string

First name of the insured

lastName
string

Last name of the insured

dob
string <date>

Date of birth of the insured

groupNumber
string

Insurance group number

insuranceId
string

Insurance provider ID

payorName
string

Name of the insurance payor

object

Optional guarantor information for the patient

firstName
string

First name of the guarantor

lastName
string

Last name of the guarantor

relationship
string

Relationship to the patient. Can be either HL7 code or readable name. Valid HL7 codes are ASC, BRO, CGV, CHD, DEP, DOM, EMC, EME, EMR, EXF, FCH, FND, FTH, GCH, GRD, GRP, MGR, MTH, NCH, NON, OAD, OTH, OWN, PAR, SCH, SEL, SIB, SIS, SPO, TRA, UNK, WRD. Readable names include mother, father, spouse, self, sibling, etc.

dob
string <date>

Date of birth of the guarantor

gender
string
Enum: "M" "F" "U"

Gender of the guarantor (M=Male, F=Female, U=Unknown)

phone
string

Phone number of the guarantor

object

Address of the guarantor

Array of objects

Optional diagnosis information for the order

Array
code
string

Diagnosis code (e.g., ICD-10)

description
string

Description of the diagnosis

system
string

Coding system used (e.g., ICD-10-CM)

type
string
Enum: "A" "F" "W"

Diagnosis type. A = Admitting, F = Final, W = Working

diagnosisDate
string <date>

Date of diagnosis

Responses

Request samples

Content type
application/json
{
}

Response samples

Content type
application/json
{
}

Provider

Ordering clinicians (NPI) linked to your organization and locations. Used to record the ordering provider on lab orders for regulatory and billing compliance.

List Providers (V3)

Lists ordering providers for your organization with optional status filter and pagination.

Authorizations:
apiKey
query Parameters
org_id
string

Filter providers by organization ID. Defaults to the API key's organization.

active_status
string
Enum: "ACTIVE" "INACTIVE" "RETIRED"

Filter by provider active status.

page
integer
Default: 1
limit
integer <= 100
Default: 20

Responses

Response samples

Content type
application/json
{
}

System

Health checks (no API key required on some environments).

Check Labflow API Health (V3)

Returns platform health and dependency status for monitoring and readiness checks.

Authorizations:
apiKey

Responses

Response samples

Content type
application/json
{
}