Skip to main content
Lab ordering places an order for one or more lab tests with OpenLoop’s lab network, for a patient who already exists in your organization. It is available by arrangement: your credentials are granted the laboratories:write permission when lab ordering is set up for you. Confirm with your OLH implementation contact that it is, in each environment, before your first call.

What you’ll do

1

Get your lab setup from your implementation contact

The lab_test_ids you may order, which of them take a collection_method, and confirmation that your credentials carry laboratories:write in staging and in production.
2

Make sure the patient record is complete

Name, birth date, phone, email and a full home address. The order is built from the patient record, not from the request body.
3

Place the order

POST /v0.1/laboratories with the patient id, the test ids and an Idempotency-Key. Add a collection method only for tests that support more than one.
4

Store what comes back

data.order_id and request_id. There is no way to read the order back on this API yet.

Before your first order

Recipe · Make sure the patient record is complete

The lab order is built from the patient record at the moment you call. Every field below must be present, or the call returns 400 listing what is missing. The birth date and postal code must also be in the format shown, or the call returns 400 saying the patient record has fields the lab network cannot accept. Both messages name the fields as they appear on POST /v0.1/patients.
curl
Keep data.id from the response: it is the patient_id you order against.
The lab network applies its own rules to the patient record. First and last names are limited to 50 characters there, while POST /v0.1/patients accepts up to 100. For walk_in_test, the address must be in the lab network’s service area. A record that breaks either rule is rejected with the 400 described under Errors even though the patient record accepted it, and needs correcting before the order can be placed.

Recipe · Place the order

Store data.order_id and request_id together. They are what we need to find the order if you contact us about it.

Recipe · Retry without ordering twice

Send an Idempotency-Key header on every call: a UUID your client generates once per intended order, stored before you send, and reused unchanged on every retry of that order. So a genuinely new order for tests the patient has had before, such as a repeat panel, needs a new key. The key is not compared against the body: never reuse one for a different order, because you will get the first order back. Never drop the key on a retry. Either kind of match is held for two years. Leading and trailing whitespace is trimmed from the key. A key that is then empty, or longer than 200 characters, is not rejected: it is ignored, and the request is handled as if no key were sent, so keep keys to 200 characters or fewer. A 502 with NETWORK_ERROR, or with PROVIDER_ERROR and any other message, can be retried once with the same key.
A 502 that says an earlier request is still being processed may not clear. If that earlier request is still running, the answer changes once it finishes. If the lab network did not confirm whether the earlier attempt placed the order, every retry under that key, or without a key for the same tests, keeps answering 502 and retrying does not clear it. Contact us with the request_id. Do not switch to a new key to get past it: if the earlier order was placed, a new key places a second one.

Errors

Every error uses the standard envelope, { error: { message, error_code }, request_id }. See Errors.

What is not available yet

Getting started

Hosts, credentials and the token exchange

Integration flow

Creating the patient this order is placed for

Retries and idempotency

How Idempotency-Key behaves across the API

Errors

The error envelope, request_id, and what each status means