How to order Quest labs through an API

To order Quest Diagnostics tests from your own software you need three things: a programmatic connection to Quest, a licensed ordering provider with an active NPI, and a HIPAA-compliant place for the patient record. LabLink provides the connection through one REST API, on an existing Quest interface, and keeps patient data under your organization.

With LabLink you create a patient, pick tests from Quest's catalog, place an order with the ordering provider, diagnosis codes and bill type, follow its status, and receive signed webhooks when Quest has the requisition and when results are posted. This guide walks through each step and what to plan for.

Before you write code

Most teams discover at least one of these late. None of them block building in sandbox; all of them are needed before your first real order.

• An ordering provider with an NPI. Every order is placed under a licensed ordering provider with an active NPI. Your own clinician or a telehealth partner both work. CareGap does not originate lab orders.
• A Quest relationship. Bring your existing Quest account, or have LabLink set up a Quest subaccount for you. See ordering without your own Quest account.
• A signed Platform Agreement and BAA. Results are protected health information, so the BAA is signed before go-live.
• A decision on who pays. Each order carries a bill type, and insurance orders need extra data. See the bill type table below.

The order lifecycle

Every call goes to https://lablink.caregap.io/api/sandbox/v1 in sandbox or https://lablink.caregap.io/api/v1 in production, with Authorization: Bearer <key> and a key for the same environment.

1. Create or look up the patient with POST /patients. Only first name, last name and date of birth are required. Send your own externalId: a retried create returns conflict with the existing id, and GET /patients?externalId= finds the patient later. Without one, every call creates a new patient; LabLink never merges on similar names. Patient records are billed per patient per year, so duplicates cost money as well as causing confusion.
2. Pick tests from the catalog. GET /tests?search= matches part of a name and code= part of a Quest order code. Then call GET /tests/{id} for each test: some have ask-at-order-entry questions, and an order is not created until every one is answered. Ask them while the order is being put together, not afterwards.
3. Place the order with POST /orders: patient, address (the first time you order for a patient), up to 25 tests, the provider's NPI, up to 10 ICD-10-CM diagnosis codes, bill type and answers, in one request. LabLink completes the questionnaire and provider authorization. If it cannot, the order is still created and comes back with actionRequired.
4. Finish anything outstanding. actionRequired.type is answer_questions, choose_provider or choose_billing, finished with POST /orders/{id}/answers, /provider or /billing. Its message says which.
5. Follow the status. GET /orders/{id} returns created, then awaiting_collection once Quest has the requisition, then results_final; or cancelled. Branch on status and actionRequired, not on step names.
6. Receive webhooks. order.awaiting_collection says the patient can be drawn: download the requisition PDF they bring with GET /orders/{id}/requisition. order.results_final carries Quest's results message, HL7 v2 parsed to JSON, and the PDF report. See retrieving Quest results programmatically.

Request bodies, every field and the errors for each call are in the API docs and the OpenAPI spec, and the first sandbox order walkthrough has copy-paste requests for each step. The playground in the LabLink console sends every call in sandbox.

Sandbox and production

Choosing a bill type per order

You can use different bill types for different orders. LabLink's own platform fees apply to every order whatever the bill type; see LabLink pricing.

Implementation notes

• Make patient creation idempotent with externalId, and look patients up before creating them.
• Handle errors in one place: every error is { error: { type, message, param, requestId } }. Branch on type. A platform_unavailable (502) is safe to retry for reads; check before retrying a create.
• Unknown fields are rejected, not ignored, so a typo fails loudly instead of being dropped.
• Drive your UI from actionRequired rather than hard-coding the steps an order goes through.
• Verify webhook signatures against the raw body, dedupe events on id (delivery is at least once), and keep sandbox and production endpoints and secrets separate.
• Keep API keys server side. Never put them in a browser or mobile app bundle.
• Keep patient data and results out of application logs, analytics and error trackers.
• Patients in Rhode Island are not served.
• If you client bill and re-bill patients, have counsel review state direct-bill, anti-markup and disclosure rules before you publish prices.

What LabLink does not do

• Originate lab orders. Your licensed ordering provider authorizes every order.
• Sell, bill or collect for laboratory testing. Quest bills according to the bill type.
• Interpret results. Clinical follow-up stays with your ordering provider.