Lab Order

A lab order is a request for one or more lab tests for a patient. Create the order as a draft, update it until it is ready, then submit it to send it to the lab. When the lab reports results, they appear as a lab result linked to the order.

The lab order model

Properties

Name
id
Type
string
Description
Unique identifier for the lab order.
Name
object
Type
string
Description
Always 'lab_order'.
Name
patient
Type
string
Description
Patient the lab order is for.
Name
name
Type
string
Description
Name of the lab order.
Name
ordering_provider
Type
string
Description
Provider who ordered the lab tests.
Name
order_details
Type
string
Description
Free-text details about the order.
Name
billing_type
Type
string
Description
Who is billed for the order. One of 'client_bill', 'commercial_insurance', or 'patient_bill'.
Name
insurance_policy
Type
string
Description
Insurance policy billed for the order. Only set when billing_type is 'commercial_insurance', otherwise null.
Name
share_with_patient
Type
boolean
Description
Whether the order is shared with the patient.
Name
tests
Type
array of objects
Description
Lab tests on the order.
Name
tests.id
Type
number
Description
Unique identifier for the lab test on this order.
Name
tests.test
Type
string
Description
ID of the lab test (marker) being ordered.
Name
tests.name
Type
string
Description
Name of the lab test.
Name
tests.price
Type
string
Description
Price of the lab test, if available.
Name
tests.associated_diagnoses
Type
array of objects
Description
Diagnoses (ICD-10 codes) that justify the test. Each has a code and a description.
Name
tests.aoe_answers
Type
array of objects
Description
Answers to the lab's ask-on-order-entry (AOE) questions for the test.
Name
status_history
Type
array of objects
Description
Status changes for the order, oldest first. Status is one of 'draft', 'ordered', 'requisition_created', 'appointment_pending', 'appointment_scheduled', 'partial_results', or 'completed'.
Name
created_by
Type
string
Description
Creator of the lab order.
Name
created_at
Type
number
Description
Timestamp (in ISO 8601 format) of when the lab order was created.
Name
last_updated_at
Type
number
Description
Timestamp (in ISO 8601 format) of when the lab order was last updated.

Response

{
  "id": "lord_2UxtAULYUrX7GVsTKePy",
  "object": "lab_order",
  "patient": "user_Z1zXZKvqrpwxbznuW6lJ",

  "name": "Lab Order: September 28, 2026",
  "ordering_provider": "user_xeDpGyt67wTor93qKtS7",
  "order_details": "Fasting required.",
  "billing_type": "commercial_insurance",
  "insurance_policy": "iply_Hk3n8JdQpX2mRtYvLc9A",
  "share_with_patient": false,

  "tests": [
    {
      "id": 1042,
      "test": "236",
      "name": "Lipid Panel",
      "price": null,
      "associated_diagnoses": [
        {
          "code": "E78.5",
          "description": "E78.5: Hyperlipidemia, unspecified"
        }
      ],
      "aoe_answers": []
    }
  ],

  "status_history": [
    {
      "status": "draft",
      "changed_at": "2026-09-28T15:02:11.781Z",
      "changed_by": "automationBot"
    }
  ],

  "created_by": "user_xeDpGyt67wTor93qKtS7",
  "created_at": "2026-09-28T15:02:11.781Z",
  "last_updated_at": "2026-09-28T15:02:11.781Z"
}

POST/v2/lab_orders

Create a lab order

Creates a lab order in the draft status. The order is not sent to the lab until you submit it.

Required attributes

Name
patient
Type
string
Description
Patient the lab order is for.
Name
ordering_provider
Type
string
Description
Provider who is ordering the lab tests.

Optional attributes

Name
name
Type
string
Description
Name of the lab order. Defaults to 'Lab Order: <today's date>'.
Name
order_details
Type
string
Description
Free-text details about the order.
Name
billing_type
Type
string
Description
Who is billed for the order. One of 'client_bill', 'commercial_insurance', or 'patient_bill'. Defaults to 'client_bill'.
Name
insurance_policy
Type
string
Description
Insurance policy to bill. Only saved when billing_type is 'commercial_insurance'.
Name
share_with_patient
Type
boolean
Description
Whether to share the order with the patient. Defaults to false.
Name
tests
Type
array of objects
Description
Lab tests to add to the order.
Name
tests.test
Type
string
Description
ID of the lab test (marker) to order.
Name
tests.associated_diagnoses
Type
array of objects
Description
Diagnoses that justify the test, each as { code } with an ICD-10 code.
Name
tests.aoe_answers
Type
array of objects
Description
Answers to the lab's ask-on-order-entry questions, each with marker, question, answer, and optionally name and options.

Request

POST

/v2/lab_orders

curl -X POST "https://{{base_subdomain}}.avonhealth.com/v2/lab_orders" \
  -H "Authorization: Bearer {{token}}" \
  -H "x-jwt: {{jwt}}" \
  -H "account: {{account}}" \
  -H "Content-Type: application/json" \
  --data '{
    "patient": "user_Z1zXZKvqrpwxbznuW6lJ",
    "ordering_provider": "user_xeDpGyt67wTor93qKtS7",
    "order_details": "Fasting required.",
    "billing_type": "commercial_insurance",
    "insurance_policy": "iply_Hk3n8JdQpX2mRtYvLc9A",
    "tests": [
      {
        "test": "236",
        "associated_diagnoses": [{ "code": "E78.5" }]
      }
    ]
  }'

Response

{
  "id": "lord_2UxtAULYUrX7GVsTKePy",
  "object": "lab_order",
  "patient": "user_Z1zXZKvqrpwxbznuW6lJ",

  "name": "Lab Order: September 28, 2026",
  "ordering_provider": "user_xeDpGyt67wTor93qKtS7",
  "order_details": "Fasting required.",
  "billing_type": "commercial_insurance",
  "insurance_policy": "iply_Hk3n8JdQpX2mRtYvLc9A",
  "share_with_patient": false,

  "tests": [
    {
      "id": 1042,
      "test": "236",
      "name": "Lipid Panel",
      "price": null,
      "associated_diagnoses": [
        {
          "code": "E78.5",
          "description": "E78.5: Hyperlipidemia, unspecified"
        }
      ],
      "aoe_answers": []
    }
  ],

  "status_history": [
    {
      "status": "draft",
      "changed_at": "2026-09-28T15:02:11.781Z",
      "changed_by": "automationBot"
    }
  ],

  "created_by": "user_xeDpGyt67wTor93qKtS7",
  "created_at": "2026-09-28T15:02:11.781Z",
  "last_updated_at": "2026-09-28T15:02:11.781Z"
}

GET/v2/lab_orders/:id

Retrieve a lab order

Retrieves the specified lab order, including its tests and status history.

Request

GET

/v2/lab_orders/:id

curl "https://{{base_subdomain}}.avonhealth.com/v2/lab_orders/:id" \
  -H "Authorization: Bearer {{token}}" \
  -H "x-jwt: {{jwt}}" \
  -H "account: {{account}}"

Response

{
  "id": "lord_2UxtAULYUrX7GVsTKePy",
  "object": "lab_order",
  "patient": "user_Z1zXZKvqrpwxbznuW6lJ",

  "name": "Lab Order: September 28, 2026",
  "ordering_provider": "user_xeDpGyt67wTor93qKtS7",
  "order_details": "Fasting required.",
  "billing_type": "commercial_insurance",
  "insurance_policy": "iply_Hk3n8JdQpX2mRtYvLc9A",
  "share_with_patient": false,

  "tests": [
    {
      "id": 1042,
      "test": "236",
      "name": "Lipid Panel",
      "price": null,
      "associated_diagnoses": [
        {
          "code": "E78.5",
          "description": "E78.5: Hyperlipidemia, unspecified"
        }
      ],
      "aoe_answers": []
    }
  ],

  "status_history": [
    {
      "status": "draft",
      "changed_at": "2026-09-28T15:02:11.781Z",
      "changed_by": "automationBot"
    }
  ],

  "created_by": "user_xeDpGyt67wTor93qKtS7",
  "created_at": "2026-09-28T15:02:11.781Z",
  "last_updated_at": "2026-09-28T15:02:11.781Z"
}

POST/v2/lab_orders/:id

Update a lab order

Updates the specified lab order by setting the values of the parameters passed. Any other parameters not provided will not be modified. Tests can't be changed with this endpoint.

If you change billing_type to anything other than 'commercial_insurance', the order's insurance_policy is cleared.

Optional attributes

Name
name
Type
string
Description
Name of the lab order.
Name
ordering_provider
Type
string
Description
Provider who is ordering the lab tests.
Name
order_details
Type
string
Description
Free-text details about the order.
Name
billing_type
Type
string
Description
Who is billed for the order. One of 'client_bill', 'commercial_insurance', or 'patient_bill'.
Name
insurance_policy
Type
string
Description
Insurance policy to bill. Required before submitting when billing_type is 'commercial_insurance'.
Name
share_with_patient
Type
boolean
Description
Whether to share the order with the patient.

Request

POST

/v2/lab_orders/:id

curl -X POST "https://{{base_subdomain}}.avonhealth.com/v2/lab_orders/:id" \
  -H "Authorization: Bearer {{token}}" \
  -H "x-jwt: {{jwt}}" \
  -H "account: {{account}}" \
  -H "Content-Type: application/json" \
  --data '{
    "billing_type": "patient_bill",
    "share_with_patient": true
  }'

Response

{
  "id": "lord_2UxtAULYUrX7GVsTKePy",
  "object": "lab_order",
  "patient": "user_Z1zXZKvqrpwxbznuW6lJ",

  "name": "Lab Order: September 28, 2026",
  "ordering_provider": "user_xeDpGyt67wTor93qKtS7",
  "order_details": "Fasting required.",
  "billing_type": "patient_bill",
  "insurance_policy": null,
  "share_with_patient": true,

  "tests": [
    {
      "id": 1042,
      "test": "236",
      "name": "Lipid Panel",
      "price": null,
      "associated_diagnoses": [
        {
          "code": "E78.5",
          "description": "E78.5: Hyperlipidemia, unspecified"
        }
      ],
      "aoe_answers": []
    }
  ],

  "status_history": [
    {
      "status": "draft",
      "changed_at": "2026-09-28T15:02:11.781Z",
      "changed_by": "automationBot"
    }
  ],

  "created_by": "user_xeDpGyt67wTor93qKtS7",
  "created_at": "2026-09-28T15:02:11.781Z",
  "last_updated_at": "2026-09-28T15:20:43.102Z"
}

DELETE/v2/lab_orders/:id

Delete a lab order

Permanently deletes the specified lab order, along with its tests, associated diagnoses, and AOE answers.

Deleting an order that has already been submitted removes it from Avon but does not cancel it with the lab.

Request

DELETE

/v2/lab_orders/:id

curl -X DELETE "https://{{base_subdomain}}.avonhealth.com/v2/lab_orders/:id" \
  -H "Authorization: Bearer {{token}}" \
  -H "x-jwt: {{jwt}}" \
  -H "account: {{account}}"

Response

{
  "id": "lord_2UxtAULYUrX7GVsTKePy",
  "object": "lab_order",
  "deleted": true
}

POST/v2/lab_orders/:id/submit

Submit a lab order

Sends the lab order to the lab and moves its status to ordered. No request body is needed.

Before submitting, make sure:

The order has a valid billing_type, and an insurance_policy if the billing type is 'commercial_insurance'.
The patient has a first name, last name, date of birth, gender, email, phone, and an address.
The ordering provider has an NPI and licensed states.
Patients under 18 have a guarantor.

If any of these are missing, the request fails with a message naming the missing field. A successful submit returns an empty response. Retrieve the lab order to see its new status. The status keeps updating as the lab processes the order, and when results are ready they are added as a lab result.

Request

POST

/v2/lab_orders/:id/submit

curl -X POST "https://{{base_subdomain}}.avonhealth.com/v2/lab_orders/:id/submit" \
  -H "Authorization: Bearer {{token}}" \
  -H "x-jwt: {{jwt}}" \
  -H "account: {{account}}"

Error response

{
  "message": "insurance_policy is required for commercial insurance billing",
  "error": {
    "name": "CustomError",
    "status": 400,
    "code": "insurance_policy_required",
    "message": "insurance_policy is required for commercial insurance billing"
  }
}

GET/v2/lab_orders

List all lab orders

Returns a list of lab orders.

Optional query parameters

Name
patient
Type
string
Description
Only return lab orders for this patient.
Name
share_with_patient
Type
boolean
Description
Only return lab orders shared with the patient.
Name
search
Type
string
Description
Only return lab orders whose name contains this text (case-insensitive).
Name
search_from
Type
string
Description
Only return lab orders created on or after this timestamp (ISO 8601).
Name
search_until
Type
string
Description
Only return lab orders created on or before this timestamp (ISO 8601).
Name
search_on
Type
string
Description
Only return lab orders created on this date (YYYY-MM-DD).
Name
limit
Type
number
Description
Maximum number of results to return.
Name
offset
Type
number
Description
Number of results to skip.

Request

GET

/v2/lab_orders

curl "https://{{base_subdomain}}.avonhealth.com/v2/lab_orders?patient=user_Z1zXZKvqrpwxbznuW6lJ" \
  -H "Authorization: Bearer {{token}}" \
  -H "x-jwt: {{jwt}}" \
  -H "account: {{account}}"

Response

{
  "object": "list",
  "data": [
    {
      "id": "lord_2UxtAULYUrX7GVsTKePy",
      "object": "lab_order",
      "patient": "user_Z1zXZKvqrpwxbznuW6lJ",

      "name": "Lab Order: September 28, 2026",
      "ordering_provider": "user_xeDpGyt67wTor93qKtS7",
      "order_details": "Fasting required.",
      "billing_type": "commercial_insurance",
      "insurance_policy": "iply_Hk3n8JdQpX2mRtYvLc9A",
      "share_with_patient": false,

      "tests": [
        {
          "id": 1042,
          "test": "236",
          "name": "Lipid Panel",
          "price": null,
          "associated_diagnoses": [
            {
              "code": "E78.5",
              "description": "E78.5: Hyperlipidemia, unspecified"
            }
          ],
          "aoe_answers": []
        }
      ],

      "status_history": [
        {
          "status": "draft",
          "changed_at": "2026-09-28T15:02:11.781Z",
          "changed_by": "automationBot"
        },
        {
          "status": "ordered",
          "changed_at": "2026-09-28T15:31:05.440Z",
          "changed_by": "automationBot"
        }
      ],

      "created_by": "user_xeDpGyt67wTor93qKtS7",
      "created_at": "2026-09-28T15:02:11.781Z",
      "last_updated_at": "2026-09-28T15:20:43.102Z"
    }
  ]
}