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 returns400 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
data.id from the response: it is the patient_id you order against.
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 anIdempotency-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.
Errors
Every error uses the standard envelope,{ error: { message, error_code }, request_id }. See
Errors.
What is not available yet
Related
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 APIErrors
The error envelope,
request_id, and what each status means
