> ## Documentation Index
> Fetch the complete documentation index at: https://openloop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create lab requisition

> Order one or more lab tests for a patient in your organization. The order is placed with OpenLoop's lab network using the patient's name, date of birth, gender, phone, email and home address as stored on the patient record, so those fields must be present before you call this endpoint (see the `400` response).

Send the `lab_test_ids` your OLH implementation contact confirms for your organization. Leave `collection_method` out unless a test supports more than one method. A `201` means the order was accepted by the lab network; there is no read-back of the order or its results on this API yet.

**Retries and duplicates.** Send an `Idempotency-Key` on every call. A repeat under the same key for the same patient returns the original order instead of placing a second one. Without a key, a repeat request for the same patient and the same set of `lab_test_ids` as an earlier order that was also placed without a key returns that order, so a genuinely new order for the same tests needs a new key. A request with a key never matches one without: retrying a keyed request without its key places a second order. Either match is held for two years.

Lab ordering is available by arrangement: your credentials are granted `laboratories:write` when it is set up for your organization.

**Permissions:** `laboratories:write`



## OpenAPI

````yaml /openapi.json post /laboratories
openapi: 3.1.0
info:
  title: OpenLoop API
  version: 0.1.0
  description: >-
    Unified reference for the OpenLoop Patient (clinical) and Payments & Revenue
    APIs.
servers:
  - url: https://api.openloophealth.com/v0.1
    description: Production partner edge
  - url: https://api-staging.openloophealth.com/v0.1
    description: Staging partner edge (sandbox credentials)
security: []
paths:
  /laboratories:
    post:
      tags:
        - Laboratories
      summary: Create lab requisition
      description: >-
        Order one or more lab tests for a patient in your organization. The
        order is placed with OpenLoop's lab network using the patient's name,
        date of birth, gender, phone, email and home address as stored on the
        patient record, so those fields must be present before you call this
        endpoint (see the `400` response).


        Send the `lab_test_ids` your OLH implementation contact confirms for
        your organization. Leave `collection_method` out unless a test supports
        more than one method. A `201` means the order was accepted by the lab
        network; there is no read-back of the order or its results on this API
        yet.


        **Retries and duplicates.** Send an `Idempotency-Key` on every call. A
        repeat under the same key for the same patient returns the original
        order instead of placing a second one. Without a key, a repeat request
        for the same patient and the same set of `lab_test_ids` as an earlier
        order that was also placed without a key returns that order, so a
        genuinely new order for the same tests needs a new key. A request with a
        key never matches one without: retrying a keyed request without its key
        places a second order. Either match is held for two years.


        Lab ordering is available by arrangement: your credentials are granted
        `laboratories:write` when it is set up for your organization.


        **Permissions:** `laboratories:write`
      parameters:
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
          description: >-
            Recommended. A UUID your client generates once per intended order
            and reuses on every retry of that order. A retry under the same key
            for the same patient returns the original order with `201` instead
            of placing a second one. A key is not compared against the request
            body, so never reuse a key for a different order, and never drop the
            key on a retry: a request without a key does not match one sent with
            a key. Leading and trailing whitespace is trimmed. 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.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                patient_id:
                  type: string
                  minLength: 1
                  maxLength: 64
                  description: >-
                    The `id` of a patient in your organization, as returned by
                    `POST /v0.1/patients` or `GET /v0.1/patients`. A patient
                    outside your organization returns `404`.
                lab_test_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                  minItems: 1
                  maxItems: 20
                  description: >-
                    1 to 20 lab test ids (UUIDs), provided by your OLH
                    implementation contact for each environment. Always send
                    this field: when it is omitted the order falls back to an
                    environment default that is not specific to your
                    organization, and where no default is configured the request
                    returns `400`.
                collection_method:
                  type:
                    - string
                    - 'null'
                  enum:
                    - testkit
                    - walk_in_test
                    - at_home_phlebotomy
                    - on_site_collection
                    - null
                  description: >-
                    How the sample is collected: `walk_in_test` (patient visits
                    a lab draw site), `testkit` (kit mailed to the patient),
                    `at_home_phlebotomy`, or `on_site_collection`. Optional:
                    `null`, an empty string, or omitting the field all mean no
                    collection method is sent with the order. Leave it out for
                    tests that have a single collection method: the lab network
                    uses that method, and rejects the order if one is sent. Send
                    it only for tests that support more than one method; if the
                    lab network rejects it, the request returns `400` with the
                    order-rejected message.
                passthrough:
                  type:
                    - string
                    - 'null'
                  maxLength: 256
                  description: >-
                    Optional correlation string of your own, up to 256
                    characters, stored with the order at the lab network. It is
                    not returned in the response. Do not put patient information
                    in it.
                activate_by:
                  type: string
                  pattern: ^\d{4}-\d{2}-\d{2}$
                  description: >-
                    Optional date (`YYYY-MM-DD`) on which the order should be
                    activated, to schedule an order ahead of time. Omit it to
                    activate the order immediately.
              required:
                - patient_id
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/LabRequisition'
                  request_id:
                    type: string
                required:
                  - data
                  - request_id
        '400':
          description: >-
            `VALIDATION_ERROR`. Validation error, including patient demographics
            the lab network requires that are missing or malformed on the
            patient record. One of: the body failed validation (the message
            names the field); no `lab_test_ids` were sent and no default
            applies; the patient record is missing fields the lab order needs
            (the message lists them by their `POST /v0.1/patients` names:
            `first_name`, `last_name`, `birth_date`, `phone`, `email`,
            `addresses[].line[0]`, `addresses[].city`, `addresses[].state`,
            `addresses[].postal_code`); the patient record has fields the lab
            network cannot accept (the message lists `birth_date` when it is not
            a full `YYYY-MM-DD` date or is in the future, and
            `addresses[].postal_code` when it is not a five-digit ZIP or ZIP+4);
            or the lab network rejected the order (`the lab provider rejected
            the order: check that every lab_test_id is valid for this
            environment and, if sent, that collection_method is supported by
            those tests`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            `FORBIDDEN`. The bearer token is missing the `laboratories:write`
            permission (message `insufficient_permissions`), or your
            organization is not provisioned (message `organization is not
            provisioned for this request`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            `NOT_FOUND`. No patient with this `patient_id` exists in your
            organization, or the lab network answered not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: >-
            `PROVIDER_ERROR` or `NETWORK_ERROR`. The lab network failed: it
            returned an error (`PROVIDER_ERROR`), or could not be reached or did
            not respond in time (`NETWORK_ERROR`). Retry once with the same
            `Idempotency-Key`. The same status is returned when an earlier
            request for this order is still being processed (message `a previous
            request for this patient is still being processed; retry later`). If
            the lab network did not confirm whether that earlier attempt placed
            the order, repeat requests for that order keep answering `502` and
            retrying does not clear it: contact us with the `request_id`, and do
            not retry under a new key, which can place a duplicate order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - serviceToken:
            - laboratories:write
        - userToken:
            - laboratories:write
components:
  schemas:
    LabRequisition:
      type: object
      properties:
        order_id:
          type: string
          description: >-
            The lab order id. Store it and quote it, with `request_id`, when you
            contact us about this order.
        junction_user_id:
          type: string
          description: >-
            The lab network's id for this patient. Stable across orders for the
            same patient.
        patient_id:
          type: string
          description: The patient the order was placed for.
        lab_test_ids:
          type: array
          items:
            type: string
          description: >-
            The lab test ids ordered: the ones in your request, or the
            environment default when you omitted `lab_test_ids`.
        collection_method:
          type: string
          description: >-
            The collection method from your request. Absent when you did not
            send one.
        status:
          type: string
          description: Always `requisition_created` on this response.
      required:
        - order_id
        - junction_user_id
        - patient_id
        - lab_test_ids
        - status
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            error_code:
              type: string
          required:
            - message
            - error_code
        request_id:
          type: string
      required:
        - error
        - request_id
  securitySchemes:
    serviceToken:
      type: oauth2
      description: >-
        Service (M2M) access token issued by POST /auth/token using the
        client_credentials grant. Required scopes, where known, are listed on
        each operation below.
      flows:
        clientCredentials:
          tokenUrl: https://api.openloophealth.com/v0.1/auth/token
          scopes: {}
    userToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        User access token issued by POST /auth/token via the verification-code
        grant (after Verify a one-time code) or the refresh_token grant.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.