🚧

Onboarding a Lab

Before you can submit orders to a lab you must first create a Route for the lab, specifying your account number with the lab.

Routes represent that a provider or office has an account with a lab. Routes are created on a per customer (provider/office) basis, and a customer can have many Routes to various labs.

The Oystehr Lab Service provides three endpoints to manage Routes: Create, Get Route, and Delete Route.

You can view a list of the supported labs here (opens in a new tab).

Create Route

In order to create a Route, the customer will need to provide the lab-furnished Account Number. This Account Number will come as the product of your customer negotiating a relationship with a particular lab. Account Numbers must be unique to a customer and lab pair.

In addition to the Account Number, some labs also require additional parameters in order to establish a Route. These values should be obtained by your customer from their negotiations with the lab. These parameters are optional in the Lab Service API, but required by certain labs. Note that "EULA" refers to an End User License Agreement. See the API reference for Create Route (opens in a new tab).

primaryName — Name of the Primary (Practice or Provider depending on the Route). e.g. 'Sample Practice'
primaryAddress — Address of the Primary
eulaVersion — The version number of the EULA. e.g. '1.2.0'
eulaAccepterFullName — Full name of who accepted the EULA, e.g.
eulaAcceptanceDateTimeUtc — Date and time the EULA was accepted. Must be a valid ISO date string. Note that the time can be omitted.
clientSiteId — Site ID for the Primary. ClientSiteID is assigned by the lab. This disambiguates instances where the same Account Number is used across multiple physical locations.

Here is an example showing the structure of each of these fields along with example values:

Example Create Route Additional Fields

{
  "primaryName": "Sample Practice",
  "primaryAddress": {
    "address1": "400 Sample Lane",
    "address2": "Suite 100",
    "city": "Portland",
    "stateProvinceCode": "OR",
    "postalCode": "97217",
  },
  "eulaVersion": "1.2.0",
  "eulaAccepterFullName": "John Smith",
  "eulaAcceptanceDateTimeUtc": "2025-02-04",
}

These are the labs that require additional parameters:

LabCorp

⚠️

The Create Route endpoint will accept a request made without EULA parameters even if the lab in question requires them. However, the returned Route will be in an "inactive" state. There are two ways to activate an inactive Route: delete the Route and re-make it providing the EULA fields (this will result in a new routeGuid), or contact [email protected] for help updating your Route.

Get Route

This endpoint will return the list of all routes associated with the provided Project id, or no routes if none exist for that Project id. Read more about how to call this endpoint in the Get Route (opens in a new tab) API reference.

Here is an example Route returned by this endpoint:

Example Returned Route

{
  "routeGuid": "8dd926b3-fb96-4424-95d8-4e73368c2767",
  "labGuid": "790b282d-77e9-4697-9f59-0cef8238033a", 
  "accountNumber": "Sample-Account-Number"
}

Delete Route

If a Route has been made in error or the relationship no longer exists between a customer and a lab, the Route can be deleted by invoking the Delete Route endpoint and providing the routeGuid of the Route to be deleted. Read more about the Delete Route (opens in a new tab) endpoint in the API Reference.

Explore the Compendium Submit an Order