Skip to main content
API docs by Redocly

JustLabs Partner API (1.0.0)

Download OpenAPI specification:Download

JustLabs Partner Support: support@justlabs.health

Server-to-server API for B2B lab-ordering partners. Lets a partner browse the JustLabs catalog, find Quest Diagnostics draw sites, place lab orders for their end users, poll order status, and retrieve requisitions and results — all charged to the partner's own Stripe payment method (never the individual patient's).

All requests are JSON (Content-Type: application/json) and authenticate with a bearer API key (Authorization: Bearer jl_live_... in production, jl_test_... on the sandbox). Money is always integer cents. Dates are ISO-8601. Every error response has the shape documented under Error below.

See https://docs.justlabs.health for the full integration guide, including webhook signature verification and retry semantics.

Catalog

Get the current test/panel catalog and per-order fees

Returns every orderable test and panel, the partner's own per-order fees (lab collection + physician order), and the list of US states JustLabs cannot currently serve. Response is cacheable for a few minutes (Cache-Control: private, max-age=300).

Panels do not carry a biomarkers field — only their member tests ids. Look up each test id in tests[] for its biomarkers.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "fees": {
    },
  • "restrictedStates": [
    ],
  • "tests": [
    ],
  • "panels": [
    ]
}

Locations

Find nearby Quest Diagnostics draw sites

Search by ZIP (?zip=) or by coordinates (?lat=&lng=&radiusMiles=). Exactly one search mode is used per request — if zip is present it takes precedence; otherwise lat/lng are required.

Authorizations:
bearer
query Parameters
zip
string^\d{5}(-?\d{4})?$

5 or 9 digit US ZIP code. Mutually exclusive with lat/lng search.

lat
number

Latitude. Required (with lng) when zip is omitted.

lng
number

Longitude. Required (with lat) when zip is omitted.

radiusMiles
number <= 250
Default: 50

Search radius in miles for the lat/lng mode. Capped at 250.

limit
integer [ 1 .. 200 ]
Default: 50

Max results, 1-200.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Orders

Create a lab order

Charges the partner's Stripe payment method for the order total (sum of item prices + the partner's per-order fees) and, on success, schedules the order for automated placement at Quest.

Idempotency-Key is required (1–100 characters, [A-Za-z0-9_.-]). Retry behavior depends on the response — see "Idempotency & retries" below and https://docs.justlabs.health.

Authorizations:
bearer
header Parameters
Idempotency-Key
required
string [ 1 .. 100 ] characters

Required, 1–100 chars, [A-Za-z0-9_.-] (a UUID is fine). Any other character is rejected with 400 idempotency_key_required.

Keys are held for 24 hours from first use (IDEMPOTENCY_TTL_HOURS). Within that window, reusing a key with the SAME body replays the original outcome instead of creating a new order/charge (see "Idempotency & retries" in the guide for the exact per-status-code rules — retry behavior is NOT simply "always safe to repeat"). Once a key expires, it is treated as never having been used: reusing it mints a genuinely new order and a new charge, even if the same key was used for a real order less than a day earlier.

Request Body schema: application/json
required
externalId
string or null [ 1 .. 100 ] characters

Your own id for this order. Non-empty when present. Returned back on the order and filterable via GET /orders?externalId=.

required
object (PatientInput)
required
Array of objects [ 1 .. 25 ] items

Duplicate ids are de-duplicated server-side before pricing — sending the same id twice does not double the charge or the order line.

object (GuardianInput)

Required when the patient is under 18 at time of purchase.

preferredLocationId
string or null

A Quest location id from GET /locations. Optional.

object or null <= 20 properties

Up to 20 string key/value pairs (keys ≤40 chars, values ≤200 chars). Echoed back on the order, never used by JustLabs.

Responses

Request samples

Content type
application/json
{
  • "externalId": "string",
  • "patient": {
    },
  • "items": [
    ],
  • "guardian": {
    },
  • "preferredLocationId": "string",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "externalId": "string",
  • "status": "processing",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "items": [
    ],
  • "fees": {
    },
  • "subtotalCents": 0,
  • "totalCents": 0,
  • "payment": {
    },
  • "patient": {
    },
  • "fastingRequired": true,
  • "preferredLocation": {
    },
  • "requisition": {
    },
  • "results": {
    },
  • "metadata": {
    },
  • "cancelledAt": "2019-08-24T14:15:22Z"
}

List orders

Partner-scoped, newest first. Supports cursor pagination.

Authorizations:
bearer
query Parameters
status
string (PublicOrderStatus)
Enum: "processing" "requisition_ready" "results_ready" "cancelled"

Filter to one public status.

externalId
string

Filter to orders created with this externalId.

limit
integer [ 1 .. 100 ]
Default: 50

Page size, 1-100.

cursor
string

Opaque pagination cursor from a previous response's nextCursor.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "nextCursor": "string"
}

Get a single order

Authorizations:
bearer
path Parameters
id
required
string

The JustLabs order id, e.g. order_1758000000000_ab12cd34.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "externalId": "string",
  • "status": "processing",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "items": [
    ],
  • "fees": {
    },
  • "subtotalCents": 0,
  • "totalCents": 0,
  • "payment": {
    },
  • "patient": {
    },
  • "fastingRequired": true,
  • "preferredLocation": {
    },
  • "requisition": {
    },
  • "results": {
    },
  • "metadata": {
    },
  • "cancelledAt": "2019-08-24T14:15:22Z"
}

Cancel an order and refund the charge

Cancellable only while the order has provably never reached Quest — in practice, within about 60 minutes of creation and before a requisition has been issued. Refunds the partner's Stripe charge in the same request when possible. Takes no request body.

Authorizations:
bearer
path Parameters
id
required
string

The JustLabs order id, e.g. order_1758000000000_ab12cd34.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "externalId": "string",
  • "status": "processing",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "items": [
    ],
  • "fees": {
    },
  • "subtotalCents": 0,
  • "totalCents": 0,
  • "payment": {
    },
  • "patient": {
    },
  • "fastingRequired": true,
  • "preferredLocation": {
    },
  • "requisition": {
    },
  • "results": {
    },
  • "metadata": {
    },
  • "cancelledAt": "2019-08-24T14:15:22Z",
  • "refund": "issued"
}

Get a signed download URL for the lab requisition PDF

Available once the order's status is requisition_ready. The signed URL expires in 15 minutes — fetch a fresh one if it lapses.

Authorizations:
bearer
path Parameters
id
required
string

The JustLabs order id, e.g. order_1758000000000_ab12cd34.

Responses

Response samples

Content type
application/json
{}

Get structured results and signed PDF URLs

Available once the order's status is results_ready.

Authorizations:
bearer
path Parameters
id
required
string

The JustLabs order id, e.g. order_1758000000000_ab12cd34.

Responses

Response samples

Content type
application/json
{
  • "status": "processing",
  • "reportedAt": "2019-08-24T14:15:22Z",
  • "source": "quest",
  • "pdfs": [
    ],
  • "analytes": [
    ]
}

order.requisition_ready — sent when an order reaches requisition_ready Webhook

Delivered by JustLabs to the partner's configured webhook URL, signed with X-JustLabs-Signature (see the Webhooks page at https://docs.justlabs.health for verification). At-least-once delivery — dedupe on X-JustLabs-Delivery, not on payload content. No ordering guarantee even for deliveries on the same order (an inline first attempt and a 5-minute-granularity cron retry can race); treat data.status as a hint and re-fetch GET /orders/{id} if you need the authoritative current state.

Your endpoint must respond 2xx directly. A 3xx redirect is treated as a failed delivery attempt, not followed — JustLabs never re-POSTs a signed webhook body to a different origin. Non-2xx (including 3xx) and timeouts are retried per the backoff schedule in the guide.

Authorizations:
bearer
Request Body schema: application/json
id
required
string

Delivery id. Same value as the X-JustLabs-Delivery header — use it to dedupe (at-least-once delivery).

type
required
string
Enum: "order.requisition_ready" "order.results_ready" "order.cancelled"
createdAt
required
string <date-time>
required
object

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "type": "order.requisition_ready",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

order.results_ready — sent when an order reaches results_ready Webhook

Delivered by JustLabs to the partner's configured webhook URL, signed with X-JustLabs-Signature (see the Webhooks page at https://docs.justlabs.health for verification). At-least-once delivery — dedupe on X-JustLabs-Delivery, not on payload content. No ordering guarantee even for deliveries on the same order (an inline first attempt and a 5-minute-granularity cron retry can race); treat data.status as a hint and re-fetch GET /orders/{id} if you need the authoritative current state.

Your endpoint must respond 2xx directly. A 3xx redirect is treated as a failed delivery attempt, not followed — JustLabs never re-POSTs a signed webhook body to a different origin. Non-2xx (including 3xx) and timeouts are retried per the backoff schedule in the guide.

Authorizations:
bearer
Request Body schema: application/json
id
required
string

Delivery id. Same value as the X-JustLabs-Delivery header — use it to dedupe (at-least-once delivery).

type
required
string
Enum: "order.requisition_ready" "order.results_ready" "order.cancelled"
createdAt
required
string <date-time>
required
object

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "type": "order.requisition_ready",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

order.cancelled — sent when a partner cancels an order via DELETE /orders/{id} Webhook

Delivered by JustLabs to the partner's configured webhook URL, signed with X-JustLabs-Signature (see the Webhooks page at https://docs.justlabs.health for verification). At-least-once delivery — dedupe on X-JustLabs-Delivery, not on payload content. No ordering guarantee even for deliveries on the same order (an inline first attempt and a 5-minute-granularity cron retry can race); treat data.status as a hint and re-fetch GET /orders/{id} if you need the authoritative current state.

Your endpoint must respond 2xx directly. A 3xx redirect is treated as a failed delivery attempt, not followed — JustLabs never re-POSTs a signed webhook body to a different origin. Non-2xx (including 3xx) and timeouts are retried per the backoff schedule in the guide.

Authorizations:
bearer
Request Body schema: application/json
id
required
string

Delivery id. Same value as the X-JustLabs-Delivery header — use it to dedupe (at-least-once delivery).

type
required
string
Enum: "order.requisition_ready" "order.results_ready" "order.cancelled"
createdAt
required
string <date-time>
required
object

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "type": "order.requisition_ready",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "data": {
    }
}