NAV Navigation
cURL

Introduction

Welcome to the ButterflyLabs API!

Currently we only support REST endpoints. Endpoints are subject to change and are versioned when breaking changes are introduced. However we will announce any breaking changes and welcome feedback prior to such changes. If you have any questions, please email us with your questions.

Get started

Step 1 - Create your account

The first thing you need to do is create an account. If you are interested in setting up an account, schedule a call with us here. Once your company is in our system, you will securely receive your API keys.

You will receive a production/sandbox key pair that looks like the following:

Production Key: live:XXXXXXXXXXXXXXXXXXXXXXXX

Sandbox Key: test:XXXXXXXXXXXXXXXXXXXXXXXX

Step 2 - Familiarize yourself with the API

This documentation represents the current state of our API. They are subject to change over the course of development. We will let you know about any major changes in advance via email.

The documentation is primarily organized by resources. Most endpoints support basic actions like create, read, and update. POST requests are not idempotent. If you submit an order and are unsure if it has been received, first check if the resource exists by listing the orders resource in your account.

We support sandbox queries which allow you to submit requests and receive a variety of canned responses to help you handle different response types. Resources you create with the sandbox key are not persisted.

Testing code

To test code easily, you can either copy the requests and paste them into your terminal (assuming your machine supports the cURL tool). Otherwise, if you have the Postman app, you can copy a code example and import it into your Postman editor simply.

  1. Copy code snippet.

  2. Navigate to Postman and find the import button.

  3. Select Raw text and paste the code snippet there.

    postman

  4. Hit import.

From there you should be able to easily alter your API key header and run a request.

Sample sandbox ids

The ids used in the examples shown to the right can be used to submit GET requests that will demonstrate successful responses. Error responses can be invoked by providing input that is incorrect based on the error code description. For example, an invalid_dob error code can be produced by attempting to create a patient object with a birth date less than 18 years from today.

Sample response sandbox IDs:

Object type Id
Physician phys_HMEsOS1sACo97yxg
Patient pt_DOPl1KA3XOrx9ih5
Order ord_zAsm5nErojHjPsU7
Kit Code BFLY_HBA1C
Ordered Kit Id kt_ArMPb0eTqHst3tpf

Step 3 - Order your first test

Follow these steps to order your first test. If your account has not been enabled for ordering using our virtual physician network, you must create a physician resource and use that for ordering. Using our virtual physician network incurs additional fees on top of the order fee.

  1. Create a patient resource.
  2. Create an order.
  3. Add a webhook endpoint
  4. Get the test results.

Create a patient resource.

curl -X POST "http://api.butterflylabs.co/vbeta/patients" \
  -H "x-api-key: <API_KEY>"
  -d 'full_name=jane doe' \
  -d 'date_of_birth=2000-12-12' \
  -d 'sex=female' \
  -d 'address_line_1=123 Sunshine Plaza' \
  -d 'address_line_2=Unit 4' \
  -d 'city=Los Angeles' \
  -d 'state=CA' \
  -d 'postal_code=90004' \
  -d 'phone_number=9254073333' \
  -d 'email=jane.doe@butterflylabs.co'

Response

{
  "id": "pt_DOPl1KA3XOrx9ih5",
  "created_at": "2021-03-10T22:57:57.033Z",
  "updated_at": "2021-03-10T22:57:57.033Z",
  "full_name": "Jane Doe",
  "sex": "female",
  "phone_number": "9254071233",
  "email": "jane.doe@butterflylabs.co",
  "date_of_birth": "2000-12-12",
  "address": {
    "address_line_1": "123 Sunshine Plaza",
    "address_line_2": "Unit 4",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90004"
  }
}

1. Create patient resource

Every test requires a corresponding patient resource. You can create a patient with the patient endpoint. You can update the patient resource at a later point in time if you need to update an address. By default when you create an order for a patient, the test kit will be sent to the address on the patient resource. You can elect to send it to an alternative address at order time.

Order a test.

curl "https://api.butterflylabs.co/vbeta/orders" \
  -H "x-api-key: <API_Key>" \
  -d ordering_physician_id="phys_HMEsOS1sACo97yxg" \
  -d patient_id="pt_DOPl1KA3XOrx9ih5" \
  -d kit_code="BFLY_HBA1C"

Response

{
  "id": "ord_zAsm5nErojHjPsU7",
  "created_at": "2012-04-23T18:25:43.511Z",
  "updated_at": "2012-04-23T18:25:43.511Z",
  "status": "ACKNOWLEDGED",
  "ordering_physician": {
    "id": "phys_HMEsOS1sACo97yxg",
    "full_name": "Benjamin Franklin",
    "npi": "1234567890"
  },
  "patient": {
    "id": "pt_DOPl1KA3XOrx9ih5",
    "full_name": "Jane Doe"
  },
  "ship_to_address": {
    "address_line_1": "123 Sunshine Plaza",
    "address_line_2": "Unit 4",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90004"
  },
  "kits": [
    {
      "id": "kt_ArMPb0eTqHst3tpf",
      "code": "BFLY_HBA1C"
    }
  ]
}

Get test results

curl "https://api.butterflylabs.co/vbeta/results/<KIT_ID>" \
  -H "x-api-key: <API_KEY>"

Response

{
  "kit_id": "<KIT_ID>",
  "created_at": "2012-04-23T18:25:43.511Z",
  "updated_at": "2012-04-23T18:25:43.511Z",
  "code": "BFLY_HBA1C",
  "order_id": "ord_zAsm5nErojHjPsU7",
  "patient_id": "pt_DOPl1KA3XOrx9ih5",
  "received_date": "2020-06-18",
  "collected_date": "2020-06-16",
  "report_generated_date": "2020-06-18",
  "markers": [
    {
      "name": "HBA1C",
      "panel_id": "HBA1C_DBS",
      "result": 5.0,
      "unit_of_measure": "%",
      "result_level": "Ok",
      "range_minimum": 4.0,
      "range_maximum": 6.5,
      "comments": "Hemoglobin A1c (HbA1c), is a form of hemoglobin (a blood ..."
    }
  ]
}

2. Create an order

When an order is created, a test kit is send out to the patient. You can track the status of the test kit with the order resource. The order represents the basket of kits being sent to a specific address. Within the order resource are the kits that have been ordered. You can check the results for each kit using the kit id provided after an order.

Register an endpoint

curl "https://api.butterflylabs.co/vbeta/webhook_endpoints"
  -H "x-api-key: <API_Key>" \
  -d "url": "<HTTPS_ENDPOINT>" \ 
  -d "events": ["results.ready"]

Response

{
    "id": "we_25UiZczlRuGQhhoy",
    "created_at": "2021-05-19T17:14:47.612Z",
    "updated_at": "2021-05-19T17:14:47.612Z",
    "url": "<HTTPS_ENDPOINT>",
    "events": [
        "results.ready"
    ],
    "enabled": true
}

3. Register a webhook endpoint

To get notified when a result is ready, you can register an endpoint. You’ll receive a POST request at the registered endpoint when results are ready for the kit. Currently the only supported event is results.ready. We remove any protocols and prefixes and assume that your endpoint will be accessible regardless of whether www or non-www prefix is your canonical endpoint. From our perspective www.myendpoint.com is equivalent to myendpoint.com. We also do not support insecure requests to http endpoints.

Receive a results ready notification

{
  "event": "results.ready",
  "created_at": "2021-05-19T17:14:47.612Z",
  "kit_id": "<KIT_ID>",
}

4. Get a result

If you have registered a webhook endpoint and a result is ready for an ordered kit, you’ll receive a request to your registered endpoint. You can then make a request to the results endpoint. The events are not guaranteed to occur only once. You may receive duplicate notifications.

Authentication

ButterflyLabs uses API keys to authenticate your access to the API. You can request an API key after you’ve set up an account with us. Email us to get started. If there’s something preventing you from using our API, let us know and we can look into supporting whatever feature you might need.

ButterflyLabs expects your API key to be included in all API requests. Include the following header in all your requests:

x-api-key: <API_Key>

Orders

Order Resource

Orders represent the lifecycle of a single test kit being sent to a patient for sample collection. The order resource cannot be updated after creation. If there is an issue with an order, please contact support.

Attributes

Sample Order Object

{
  "id": "ord_zAsm5nErojHjPsU7",
  "created_at": "2012-04-23T18:25:43.511Z",
  "updated_at": "2012-04-23T18:25:43.511Z",
  "status": "ACKNOWLEDGED",
  "ordering_physician": {
    "id": "phys_HMEsOS1sACo97yxg",
    "full_name": "Benjamin Franklin",
    "npi": "1234567890"
  },
  "patient": {
    "id": "pt_DOPl1KA3XOrx9ih5",
    "full_name": "Jane Doe"
  },
  "ship_to_address": {
    "address_line_1": "123 Sunshine Plaza",
    "address_line_2": "Unit 4",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90004"
  },
  "kits": [
    {
      "id": "kt_ArMPb0eTqHst3tpf",
      "code": "BFLY_HBA1C",
      "shipping_tracking_id": "92055901755477000460652250",
      "return_shipping_tracking_id": "1Z063AX08777363907"
    }
  ]
}
id
string
The id of the order.
created_at
datetime
The datetime in UTC when the order was created. This field is immutable after creation.
updated_at
datetime
The datetime in UTC when the order was updated. This field is updated when lifecycle events occur that alter the status of the order. Customers cannot alter attributes of an order.
status
enum
The status of the order represents the lifecycle of the test kit.

ACKNOWLEDGED
The order request has been received and acknowledged.

SHIPPED_TO_PATIENT
The order request has been processed and a test kit has been sent to the address of the patient or the address specified in the order.

ARRIVED_AT_PATIENT
The test kit has arrived at the patient’s address as per the outbound shipping carrier’s tracking.

RECEIVED_BY_LAB
The test kit with a sample has been received by the lab and is pending processing.

RESULTS_READY
The tests have been run on the samples provided in the sample collection kit and the results are ready.

ERROR
There was an issue with the order. The email on file will receive the error information.

ordering_physician
object
The details of the ordering physician. See the physician resource for more information.

If an order was placed without physician information and your account has been approved for using Butterfly Labs ordering physicians, our ordering physician’s information will be listed here.
patient
object
The id and full name of the patient.
ship_to_address
object
Address the test kit was shipped to. By default, this is the patient’s address unless specified when creating an order.
kits
object[]
The details of the test kit. Currently we only support a single kit per order. Any kits after the first will be ignored.
kits[n].shipping_tracking_id
string
The tracking number for the shipment of the kit to the patient. The carrier is currently USPS, but this is subject to change. This field will be populated when the kit is shipped to the patient and the order status is changed to SHIPPED_TO_PATIENT.
kits[n].return_shipping_tracking_id
string
The tracking number for the return shipping of the kit from the patient to the lab. The carrier is currently UPS, but this is subject to change. This field will be populated when the kit is shipped to the patient and the order status is changed to SHIPPED_TO_PATIENT.

Create Order

curl "https://api.butterflylabs.co/vbeta/orders" \
  -H "x-api-key: <API_Key>" \
  -d ordering_physician_id="<PHYSICIAN_ID>" \
  -d patient_id="<PATIENT_ID>" \
  -d kit_code="<KIT_CODE>"

This endpoint is used to order a single test kit to a patient. We only support a single test kit per order at this time. Any items in a list greater than the first item will be ignored.

HTTP Request

POST https://api.butterflylabs.co/vbeta/orders

Attributes

The above command returns JSON structured like this:

{
  "id": "ord_zAsm5nErojHjPsU7",
  "created_at": "2012-04-23T18:25:43.511Z",
  "updated_at": "2012-04-23T18:25:43.511Z",
  "status": "ACKNOWLEDGED",
  "ordering_physician": {
    "id": "phys_HMEsOS1sACo97yxg",
    "full_name": "Benjamin Franklin",
    "npi": "1234567890"
  },
  "patient": {
    "id": "pt_DOPl1KA3XOrx9ih5",
    "full_name": "Jane Doe"
  },
  "ship_to_address": {
    "address_line_1": "123 Sunshine Plaza",
    "address_line_2": "Unit 4",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90004"
  },
  "kits": [
    {
      "id": "kt_ArMPb0eTqHst3tpf",
      "code": "BFLY_HBA1C",
      "shipping_tracking_id": "92055901755477000460652250",
      "return_shipping_tracking_id": "1Z063AX08777363907"
    }
  ]
}
patient_id
required
string The patient id. To create a patient, see the patient resource.
ordering_physician_id
optional
string If left empty, defaults to Butterfly Lab’s virtual physicians. If your account does not have virtual physicians enabled, this request will fail
kit_code
required
string The kit code of the test kit being sent to the address.
ship_to_address
optional
object Defaults to the address on the patient resource if unspecified.

Error Codes

Status Code Error Code Meaning
400 invalid_physician_id The physician id with the physician_id does not exist as a resource or is invalid.
400 unverified_physician_id The physician with the physician_id is not yet verified.
400 invalid_patient_id The patient with the patient_id does not exist as a resource or is invalid.
400 invalid_kit_code The kit code provided is invalid or not supported for your account.
403 illegal_sandbox_id One or more sandbox ids were used for non-sandbox use.

List Orders

curl "http://butterflylabs.co/api/vbeta/orders" \
  -H "x-api-key: <API_KEY>"

The above command returns JSON structured like this:

{
  "total": 323,
  "page": 1,
  "data": [
    {
      "id": "ord_zAsm5nErojHjPsU7",
      "created_at": "2012-04-23T18:25:43.511Z",
      "updated_at": "2012-04-23T18:25:43.511Z",
      "status": "ACKNOWLEDGED",
      "ordering_physician": {
        "id": "phys_HMEsOS1sACo97yxg",
        "full_name": "Benjamin Franklin",
        "npi": "1234567890"
      },
      "patient": {
        "id": "pt_DOPl1KA3XOrx9ih5",
        "full_name": "Jane Doe"
      },
      "ship_to_address": {
        "address_line_1": "123 Sunshine Plaza",
        "address_line_2": "Unit 4",
        "city": "Los Angeles",
        "state": "CA",
        "postal_code": "90004"
      },
      "kits": [
        {
          "id": "kt_ArMPb0eTqHst3tpf",
          "code": "BFLY_HBA1C",
          "shipping_tracking_id": "92055901755477000460652250",
          "return_shipping_tracking_id": "1Z063AX08777363907"
        }
      ]
      ...
    }
  ]
}

Lists orders by creation date descending. Only the most recent 100 orders are returned by default. For older orders, use the page query parameter to retrieve older orders.

HTTP Request

GET https://api.butterflylabs.co/vbeta/orders

Query Parameters

Parameter Default Description
page 1 Returns the page of the results. Results return a maximum of 100 records. The number of pages will always be the floor(total / 100) + 1 i.e. the 244th record will be on page 3.

Get a Specific Order

curl "http://butterflylabs.co/api/vbeta/orders/<ORDER_ID>" \
  -H "x-api-key: <API_KEY>"

The above command returns JSON structured like this:

{
  "id": "ord_zAsm5nErojHjPsU7",
  "created_at": "2012-04-23T18:25:43.511Z",
  "updated_at": "2012-04-23T18:25:43.511Z",
  "status": "ACKNOWLEDGED",
  "ordering_physician": {
    "id": "phys_HMEsOS1sACo97yxg",
    "full_name": "Benjamin Franklin",
    "npi": "1234567890"
  },
  "patient": {
    "id": "pt_DOPl1KA3XOrx9ih5",
    "full_name": "Jane Doe"
  },
  "ship_to_address": {
    "address_line_1": "123 Sunshine Plaza",
    "address_line_2": "Unit 4",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90004"
  },
  "kits": [
    {
      "id": "kt_ArMPb0eTqHst3tpf",
      "code": "BFLY_HBA1C",
      "shipping_tracking_id": "92055901755477000460652250",
      "return_shipping_tracking_id": "1Z063AX08777363907"
    }
  ]
}

This endpoint retrieves a specific order.

HTTP Request

GET http://api.butterflylabs.co/vbeta/orders/<ORDER_ID>

Physicians

Physician Resource

The physician resource represents an ordering physician who will be used by your organization to order lab tests. All lab tests require some form of physician to order a test.

Sample Physician Object

Attributes

{
  "id": "phys_HMEsOS1sACo97yxg",
  "created_at": "2021-03-08T03:27:36.086Z",
  "updated_at": "2021-03-08T03:27:36.086Z",
  "full_name": "Benjamin Franklin",
  "npi": "1234567890",
  "is_verified": true,
  "lab_accounts": [
    {
      "id": "GDX",
      "name": "Genova Diagnostics",
      "account_id": "AD990",
      "is_linked_account": true,
      "is_active": true
    }
  ]
}
id
string
The id of the physician.
created_at
datetime
The datetime in UTC that the physician resource was created. This field is immutable after creation.
updated_at
datetime
The datetime in UTC that the physician resource was updated. This field is updated when physician information is updated.
full_name
string
The physician’s full name separated by spaces.
npi
string
The physician’s national provider identifier.
is_verified
boolean
Whether we have validated the physician’s identity. Physicians whose identities have not been validated cannot be used to submit orders.
lab_accounts
object[]
A list of lab accounts the physician is associated with.
lab_account.id
string
The unique id of the lab.
lab_account.name
string
The name of the lab.
lab_account.account_id
string
The physician’s account identifier for this lab. This differs by lab. For Genova Diagnostics it is a 5 digit alphanumeric code.
lab_account.is_linked_account
string
Whether the account is linked or created by us.
lab_account.is_active
string
Whether the account is active. If true, the physician can be used to order with the lab.

Create Physician

curl -X POST "http://api.butterflylabs.co/vbeta/physicians" \
  -H "x-api-key: <API_KEY>" \
  -d "full_name=Benjamin Franklin" \
  -d "npi=1234567890"

The above command returns JSON structured like this:

{
  "id": "phys_HMEsOS1sACo97yxg",
  "created_at": "2021-03-08T03:27:36.086Z",
  "updated_at": "2021-03-08T03:27:36.086Z",
  "full_name": "Benjamin Franklin",
  "npi": "1234567890",
  "is_verified": false
}

This endpoint allows you to create a physician object.

HTTP Request

POST https://api.butterflylabs.co/vbeta/physicians

Attributes

full_name
string
The full name of the physician including middle names where applicable.
npi
string
The physician’s national provider identifier.

Error Codes

Status Code Error Code Meaning
400 invalid_or_missing_fields Certain fields are missing or invalid.
409 duplicate_physician A physician with the npi provided already exists.

Add Lab Account

curl -X POST "http://api.butterflylabs.co/vbeta/physicians/<PHYSICIAN_ID>/lab_accounts" \
  -H "x-api-key: <API_KEY>" \
  -d "lab_id=GDX" \
  -d "account_id=AD990"
{
  "id": "phys_HMEsOS1sACo97yxg",
  "created_at": "2021-03-08T03:27:36.086Z",
  "updated_at": "2021-03-08T03:27:36.086Z",
  "full_name": "Benjamin Franklin",
  "npi": "1234567890",
  "is_verified": true,
  "lab_accounts": [
    {
      "id": "GDX",
      "name": "Genova Diagnostics",
      "account_id": "AD990",
      "is_linked_account": true,
      "is_active": false
    }
  ]
}

For certain labs, you may want to link a pre-existing account for the lab with us so we may order on behalf of the physician. In those cases, use this endpoint to link their account. Account linking is only supported for labs that support this feature.

HTTP Request

POST https://api.butterflylabs.co/vbeta/physicians/<PHYSICIAN_ID>/lab_accounts

Attributes

lab_id
string
The id of the lab. Only GDX is supported at this time.
account_id
string
The account id of the physician’s lab account. This differs by lab i.e. Genova uses a 5 digit alphanumeric code as the account identifier.

Upload Verification Documents

POST https://api.butterflylabs.co/vbeta/physicians/<PHYSICIAN_ID>/verification_documents

curl "https://api.butterflylabs.co/vbeta/physicians/<PHYSICIAN_ID>/verification_documents" \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: multipart/form-data" \
  -F "data=@file.jpg"

Response 201 OK

This endpoint allows you to upload verification documents for a physician. For compliance purposes we must verify the identity of the physician ordering the test. A picture of their license or other state or federal issued documentation is acceptable.

Form Data Parameters

Parameter Description
data The file on the local file system.

Error Codes

Status Code Error Code Meaning
400 upload_failed The upload failed. Use email as an alternative.
400 invalid_or_missing_fields Certain fields are missing or invalid.

List Physicians

curl "http://butterflylabs.co/api/vbeta/physicians" \
  -H "x-api-key: <API_KEY>"

The above command returns JSON structured like this:

{
  "total": 1,
  "page": 1,
  "data": [
    {
      "id": "phys_HMEsOS1sACo97yxg",
      "created_at": "2021-03-08T03:27:36.086Z",
      "updated_at": "2021-03-08T03:27:36.086Z",
      "full_name": "Benjamin Franklin",
      "npi": "1234567890",
      "is_verified": false,
      "lab_accounts": []
    }
  ]
}

HTTP Request

GET https://api.butterflylabs.co/vbeta/physicians

Query Parameters

Parameter Default Description
page 1 Returns the page of the results. Results return a maximum of 100 records. The number of pages will always be the floor(total / 100) + 1 i.e. the 244th record will be on page 3.

Get a Specific Physician

curl "http://butterflylabs.co/api/vbeta/physicians/<PHYSICIAN_ID>" \
  -H "x-api-key: <API_KEY>"

The above command returns JSON structured like this:

{
  "id": "phys_HMEsOS1sACo97yxg",
  "created_at": "2021-03-08T03:27:36.086Z",
  "updated_at": "2021-03-08T03:27:36.086Z",
  "full_name": "Benjamin Franklin",
  "npi": "1234567890",
  "is_verified": false,
  "lab_accounts": []
}

This endpoint retrieves a specific physician.

HTTP Request

GET http://api.butterflylabs.co/vbeta/physicians/<PHYSICIAN_ID>

Patients

Patient Resource

The patient resource represents an individual to whom a test kit can be shipped and whose samples will be collected. This resource is required for two primary reasons. First, patient demographic information is used to provide interpretations for a variety of tests. Second, patient contact information must be on record for compliance.

Sample Patient Object

{
  "id": "pt_DOPl1KA3XOrx9ih5",
  "external_id": "12345",
  "created_at": "2021-03-08T03:27:36.086Z",
  "updated_at": "2021-03-08T03:27:36.086Z",
  "full_name": "Jane Doe",
  "date_of_birth": "1993-12-12",
  "sex": "female",
  "phone_number": "123-456-1235",
  "email": "jane.doe@butterflylabs.co",
  "address": {
    "address_line_1": "123 Sunshine Plaza",
    "address_line_2": "Unit 4",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90004"
  }
}

Attributes

id
string
The id of the patient.
created_at
datetime
The datetime in UTC when the patient resource was created. This field is immutable after creation.
updated_at
datetime
The datetime in UTC when the patient resource was updated. This field is updated when patient information is updated.
full_name
string
The patient’s full name separated by spaces.
date_of_birth
string
The patient’s date of birth in ISO format YYYY-MM-DD.
sex
enum
The patient’s sex (male/female).
phone_number
string
The patient’s phone number.
email
string
The patient’s email.
external_id
string
Optional - any identifier you want to assign to the patient.
address.address_line_1
string
The patient’s address line 1.
address.address_line_2
string
The patient’s address line 2.
address.city
string
The patient’s city.
address.state
string
The patient’s state as a two-digit state code.
address.postal_code
string
The patient’s postal code as a five-digit code.

Create Patient

curl "https://api.butterflylabs.co/vbeta/patients" \
  -H "x-api-key: <API_KEY>" \
  -d full_name="Jane Doe" \
  -d date_of_birth="1993-12-12" \
  -d sex="female" \
  -d address_line_1="123 Sunshine Plaza" \
  -d address_line_2="Unit 4" \
  -d city="Los Angeles" \
  -d state="CA" \
  -d postal_code="90004" \
  -d phone_number="123-456-1235" \
  -d email="jane.doe@butterflylabs.co"
  -d external_id="12345"

The above command returns JSON structured like this:

{
  "id": "pt_DOPl1KA3XOrx9ih5",
  "external_id": "12345",
  "created_at": "2021-03-08T03:27:36.086Z",
  "updated_at": "2021-03-08T03:27:36.086Z",
  "full_name": "Jane Doe",
  "date_of_birth": "1993-12-12",
  "sex": "female",
  "phone_number": "123-456-1235",
  "email": "jane.doe@butterflylabs.co",
  "address": {
    "address_line_1": "123 Sunshine Plaza",
    "address_line_2": "Unit 4",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90004"
  }
}

This endpoint allows you to create a patient object. For operations such as seeing a patient’s lab history or ordering a new test for a patient, the unique id associated with the patient should be used. Patient contact details and address can be updated through a PUT operation on the patient endpoint using the patient id.

For compliance purposes, patient contact information must be included. Any accounts found providing false data will be immediately terminated.

HTTP Request

POST https://api.butterflylabs.co/vbeta/patients

Error Codes

Status Code Error Code Meaning
400 invalid_dob The patient must be at least 18 years of age.
400 invalid_or_missing_fields Certain fields are missing or invalid.

Update Patient

curl -X PUT "https://api.butterflylabs.co/vbeta/patients/<PATIENT_ID>" \
  -H "x-api-key : <API_Key>" \
  -d full_name="Jane Doe" \
  -d date_of_birth="1993-12-12" \
  -d sex="female" \
  -d address_line_1="123 Sunshine Plaza" \
  -d address_line_2="Unit 4" \
  -d city="Los Angeles" \
  -d state="CA" \
  -d postal_code="90004" \
  -d phone_number="999-888-7777" \
  -d email="jane.doe@butterflylabs.co"
  -d external_id="12345"

The above command returns JSON structured like this:

{
  "id": "pt_DOPl1KA3XOrx9ih5",
  "external_id": "12345",
  "created_at": "2021-03-08T03:27:36.086Z",
  "updated_at": "2021-04-22T03:27:36.086Z",
  "full_name": "Jane Doe",
  "date_of_birth": "1993-12-12",
  "sex": "female",
  "phone_number": "999-888-7777",
  "email": "jane.doe@butterflylabs.co",
  "address": {
    "address_line_1": "123 Sunshine Plaza",
    "address_line_2": "Unit 4",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90004"
  }
}

This endpoint allows you to update a patient object.

HTTP Request

PUT https://api.butterflylabs.co/vbeta/patients/<PATIENT_ID>

Error Codes

Status Code Error Code Meaning
400 invalid_dob The patient must be at least 18 years of age.
400 invalid_or_missing_fields Certain fields are missing or invalid.

List Patients

curl "http://butterflylabs.co/api/vbeta/patients" \
  -H "x-api-key: <API_KEY>"

The above command returns JSON structured like this:

{
  "total": 34,
  "page": 1,
  "data": [
    {
      "id": "pt_DOPl1KA3XOrx9ih5",
      "external_id": "12345",
      "created_at": "2021-03-08T03:27:36.086Z",
      "updated_at": "2021-03-08T03:27:36.086Z",
      "full_name": "Jane Doe",
      "date_of_birth": "1993-12-12",
      "sex": "female",
      "phone_number": "123-456-1235",
      "email": "jane.doe@butterflylabs.co",
      "address": {
        "address_line_1": "123 Sunshine Plaza",
        "address_line_2": "Unit 4",
        "city": "Los Angeles",
        "state": "CA",
        "postal_code": "90004"
      }
    }
    ...
  ]
}

HTTP Request

GET https://api.butterflylabs.co/vbeta/patients

Query Parameters

Parameter Default Description
page 1 Returns the page of the results. Results return a maximum of 100 records. The number of pages will always be the floor(total / 100) + 1 i.e. the 244th record will be on page 3.

Get a Specific Patient

curl "http://butterflylabs.co/api/vbeta/patients/<PATIENT_ID>" \
  -H "x-api-key: <API_KEY>"

The above command returns JSON structured like this:

{
  "id": "pt_DOPl1KA3XOrx9ih5",
  "external_id": "12345",
  "created_at": "2021-03-08T03:27:36.086Z",
  "updated_at": "2021-03-08T03:27:36.086Z",
  "full_name": "Jane Doe",
  "date_of_birth": "1993-12-12",
  "sex": "female",
  "phone_number": "123-456-1235",
  "email": "jane.doe@butterflylabs.co",
  "address": {
    "address_line_1": "123 Sunshine Plaza",
    "address_line_2": "Unit 4",
    "city": "Los Angeles",
    "state": "CA",
    "postal_code": "90004"
  }
}

This endpoint retrieves a specific patient.

HTTP Request

GET http://api.butterflylabs.co/vbeta/orders/<PATIENT_ID>

Results

Attributes

Sample Result Object

{
  "kit_id": "kt_ArMPb0eTqHst3tpf",
  "code": "BFLY_HBA1C",
  "order_id": "ord_zAsm5nErojHjPsU7",
  "patient_id": "pt_DOPl1KA3XOrx9ih5",
  "received_date": "2020-06-18",
  "collected_date": "2020-06-16",
  "report_generated_date": "2020-06-18",
  "markers": [
    {
      "name": "HBA1C",
      "result": 5.0,
      "unit_of_measure": "%",
      "result_level": "Ok",
      "range_minimum": 4.0,
      "range_maximum": 6.5,
      "comments": "Hemoglobin A1c (HbA1c), is a form of hemoglobin (a blood pigment that carries oxygen) that is bound to glucose. Blood HbA1c levels are reflective of how well diabetes is controlled. The normal range for hemoglobin A1c is less than 5.7%. HbA1c levels are reflective of blood glucose levels over the past six to eight weeks and do not reflect daily ups and downs of blood glucose. High HbA1c levels indicate poorer control of diabetes than levels in the normal range."
    }
  ]
}
kit_id
string
A unique code for a test kit included in an order.
code
string
The code that identifies the type of test kit. See the kits resource for more information.
order_id
string
The id of the order that contained the test kits whose samples were tested.
patient_id
string
The id of the patient resource that received the tests.
received_date
date
The date the lab received the samples in ISO format YYYY-MM-DD.
collected_date
date
The date the samples were collected in ISO format YYYY-MM-DD. If the test kit doesn’t require registration this will be the date the test kit arrives at the patient’s address.
report_generated_date
string
The date the report as generated in ISO format YYYY-MM-DD.
markers
object[]
A list of markers that measured in samples provided by the test kit.

Get a specific result

curl "https://api.butterflylabs.co/vbeta/results/<KIT_ID>" \
  -H "x-api-key: <API_KEY>"

The above command returns JSON structured like this:

{
  "kit_id": "kt_ArMPb0eTqHst3tpf",
  "created_at": "2012-04-23T18:25:43.511Z",
  "updated_at": "2012-04-23T18:25:43.511Z",
  "code": "BFLY_HBA1C",
  "order_id": "ord_zAsm5nErojHjPsU7",
  "patient_id": "pt_DOPl1KA3XOrx9ih5",
  "received_date": "2020-06-18",
  "collected_date": "2020-06-16",
  "report_generated_date": "2020-06-18",
  "markers": [
    {
      "name": "HBA1C",
      "panel_id": "HBA1C_DBS",
      "result": 5.0,
      "unit_of_measure": "%",
      "result_level": "Ok",
      "range_minimum": 4.0,
      "range_maximum": 6.5,
      "comments": "Hemoglobin A1c (HbA1c), is a form of hemoglobin (a blood pigment that carries oxygen) that is bound to glucose. Blood HbA1c levels are reflective of how well diabetes is controlled. The normal range for hemoglobin A1c is less than 5.7%. HbA1c levels are reflective of blood glucose levels over the past six to eight weeks and do not reflect daily ups and downs of blood glucose. High HbA1c levels indicate poorer control of diabetes than levels in the normal range."
    }
  ]
}

This endpoint allows you to look at the results for a test kit within an order that was sent to a patient. Depending on the result itself and the type of test, the time between a test being processed by a lab and the results being ready is variable.

HTTP Request

GET https://api.butterflylabs.co/vbeta/results/<KIT_ID>

Headers

Accept: application/pdf Get the PDF version of the report. If the PDF isn’t available for any reason, you will receive a 204 status code.
Accept: application/json This is the default. Results are returned as JSON.

Response Codes

Status Code Error Code Meaning
204 no_content This report doesn’t have a corresponding PDF. Only returned when a PDF is requested.
404 not_found A kit with the provided id does not exist.
422 results_not_ready A kit with the provided id exists within our system but the results are not ready for viewing.

Kits

Attributes

code
string
The unique code that is used to reference a test kit offering.
price
number
The base price of the kit offered by the lab in cents.
name
string
The name of the kit.

List Kits

curl "https://api.butterflylabs.co/vbeta/kits" \
  -H "x-api-key: <API_KEY>"

The above command returns JSON structured like this:

{
  "total": 1,
  "page": 1,
  "data": [
    {
      "code": "BFLY_HBA1C",
      "single_kit_price_in_cents": 10000,
      "name": "Butterfly HbA1C Blood Spot Kit"
    }
  ]
}

The kits resource lists orderable test kits by your account.

HTTP Request

GET https://api.butterflylabs.co/vbeta/kits

Webhooks

Attributes

id
string
The unique id of this webhook endpoint.
created_at
number
The time the endpoint was created.
updated_at
string
The time the endpoint was updated.
url
string
The url of the endpoint.
events
string[]
The events registered to this endpoint. Currently only “results.ready” is supported.
enabled
boolean
The status of the registered endpoint. If we are unable to successfully send requests to the provided endpoint after a certain number of retries, we will disable the endpoint. You can reach out to suppor to have the endpoint re-enabled.

Register webhook endpoint

curl "https://api.butterflylabs.co/vbeta/kits" \
  -H "x-api-key: <API_Key>" \
  -d "url": "<HTTPS_ENDPOINT>" \ 
  -d "events": ["results.ready"]

The above command returns JSON structured like this:

{
    "id": "we_25UiZczlRuGQhhoy",
    "created_at": "2021-05-19T17:14:47.612Z",
    "updated_at": "2021-05-19T17:14:47.612Z",
    "url": "<HTTPS_ENDPOINT>",
    "events": [
        "results.ready"
    ],
    "enabled": true
}

Register a webhook endpoint to receive notifications when events occurr.

HTTP Request

POST https://api.butterflylabs.co/vbeta/webhook_endpoints

Errors

The standard error format contains an error code and a message.

{
  "error_code": "different_error_code_per_resource",
  "message": "A human readable description of the error",
  "status_code": "The status code of the error"
}

Common Error Codes

Status Code Error Code Meaning
404 kit_not_found Failed to find a kit definition with the provided kit code
400 invalid_dob The patient must be at least 18 years of age.
409 duplicate_patient_email The patient’s email is being used in a different record. Have you created multiple patients for the same individual?
400 invalid_or_missing_fields Certain fields are missing or invalid.
409 duplicate_physician A physician with the npi provided already exists.
400 unverified_physician_id The physician with the physician_id is not yet verified.
400 invalid_kit_code The kit code provided is invalid or not supported for your account.
400 lab_account_inactive The linked account for ordering kits from this lab is not active.
404 physician_not_found A physician with the provided id does not exist.
404 patient_not_found A patient with the provided id does not exist.
400 invalid_or_missing_fields Certain fields are missing or invalid.
400 invalid_lab_id Invalid lab id. The only supported linked lab account is with Genova Diagnostics (GDX)
422 result_not_ready A kit with the provided id exists within our system but the results are not ready for viewing.
404 result_not_found A kit with the provided id does not exist.
404 order_not_found An order with the provided id does not exist.