Partner API

Introduction

Integrate gut microbiome testing into your platform with Biomesight. The Partner API lets you offer gut microbiome testing directly inside your product. Place orders, register collection kits, retrieve analysis results, and receive real-time status updates — all through a simple REST API secured with OAuth 2.0.

The API is designed for:

• Health-tech platforms adding microbiome insights to their offering
• Wellness and nutrition apps that want to personalise recommendations with gut data
• Telehealth providers integrating lab testing into virtual consultations
• Corporate wellness programmes running gut-health screening for employees

Getting Started

Authentication

All API requests require a Bearer token. Obtain one by sending your Client ID and Client Secret using HTTP Basic authentication:

Request

curl -X POST https://app.biomesight.com/api/v1/auth/token \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials"

import requests

resp = requests.post(
    "https://app.biomesight.com/api/v1/auth/token",
    auth=("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET"),
    data={"grant_type": "client_credentials"},
)
token = resp.json()["access_token"]

Response 200 OK

{
  "access_token": "eyJhbGciOi...",
  "token_type":   "Bearer",
  "scope":        "read write",
  "expires_in":   3600
}

Include the token in subsequent requests:

Authorization: Bearer eyJhbGciOi...

Create Order

Submit an order on behalf of a customer. Biomesight will ship a collection kit to the provided address.

Request Headers

Request Body

Example Request

curl -X POST https://app.biomesight.com/api/v1/order \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORD-20250615-001",
    "purchase_date": "2025-06-15T10:30:00",
    "user": {
      "id": "CUST-12345",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com"
    },
    "destination_address": {
      "address_line1": "42 Wellness Avenue",
      "city": "London",
      "postcode_zip": "SW1A 1AA",
      "country_code": "GB"
    },
    "items": [
      { "product_sku": "YOUR_SKU", "quantity": 1 }
    ]
  }'

import requests

resp = requests.post(
    "https://app.biomesight.com/api/v1/order",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json={
        "order_id": "ORD-20250615-001",
        "purchase_date": "2025-06-15T10:30:00",
        "user": {
            "id": "CUST-12345",
            "first_name": "Jane",
            "last_name": "Smith",
            "email": "jane.smith@example.com",
        },
        "destination_address": {
            "address_line1": "42 Wellness Avenue",
            "city": "London",
            "postcode_zip": "SW1A 1AA",
            "country_code": "GB",
        },
        "items": [
            {"product_sku": "YOUR_SKU", "quantity": 1}
        ],
    },
)
print(resp.json())

Response 201 Created

{
  "status": "created",
  "sale_id": 4821,
  "external_order_id": "ORD-20250615-001"
}

Error Cases

Register Kit

After your customer collects their sample, register the kit to associate the customer with the kit ID.

Request Headers

Request Body

Example Request

curl -X POST https://app.biomesight.com/api/v1/register_kit \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORD-20250615-001",
    "kit_id": "BS1-ABC12",
    "sample_date": "2025-07-01",
    "bristol_scale": 4
  }'

import requests

resp = requests.post(
    "https://app.biomesight.com/api/v1/register_kit",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json",
    },
    json={
        "order_id": "ORD-20250615-001",
        "kit_id": "BS1-ABC12",
        "sample_date": "2025-07-01",
        "bristol_scale": 4,
    },
)
print(resp.json())

Response 200 OK

{
  "status": "Success"
}

Error Cases

Get Results

Retrieve microbiome analysis results for a registered kit. Results are available once lab processing is complete.

Request Headers

Query Parameters

Example Request

curl https://app.biomesight.com/api/v1/results/BS1-ABC12?format=json \
  -H "Authorization: Bearer eyJhbGciOi..."

import requests

resp = requests.get(
    "https://app.biomesight.com/api/v1/results/BS1-ABC12",
    headers={"Authorization": f"Bearer {token}"},
    params={"format": "json"},
)
results = resp.json()

JSON Response 200 OK

Returns a results object containing health scores and personalised recommendations.

{
  "scores": {
    "gut_health": 89.25,
    "Diversity": 88.0,
    "Probiotic": 90.07,
    "Commensal": 98.15,
    "Pathobiont": 83.33
  },
  "recommendations": {
    "food": {
      "enjoy": ["cranberries", "green tea", "pomegranate", ...],
      "avoid": ["acacia tree", "guar bean", ...]
    },
    "prebiotics": {
      "enjoy": ["Acacia fiber", "lactulose", ...],
      "reduce": ["PHGG", "psyllium", ...]
    },
    "probiotics": {
      "reduce": ["Abiotrophia defectiva"]
    }
  },
  "general": {
    "kit_id": "BS1-ABC12",
    "sample_id": 380,
    "export_date": "2026-01-09 11:49:49",
    "pipeline_id": 1
  }
}

Response Fields

PDF Response 200 OK

Returns a base64-encoded PDF report. See a sample report for the full layout. White-label partners can have the report branded as “Powered by Biomesight” with their own logo and colour scheme.

{
  "kit_id": "BS1-ABC12",
  "pdf": "JVBERi0xLjQKMS..."
}

CSV Response 200 OK

Returns a base64-encoded CSV file containing the full taxonomy breakdown for the sample. This includes abundances at every taxonomic rank (phylum, class, order, family, genus, species), giving you the raw data to power your own analysis and visualisations.

{
  "kit_id": "BS1-ABC12",
  "csv": "dGF4b25vbXksYW..."
}

Error Cases

Get Kit Status

Look up the current status of a kit/sample as it moves through the lab pipeline.

Request Headers

Example Request

curl https://app.biomesight.com/api/v1/status/kit/BS1-ABC12 \
  -H "Authorization: Bearer eyJhbGciOi..."

import requests

resp = requests.get(
    "https://app.biomesight.com/api/v1/status/kit/BS1-ABC12",
    headers={"Authorization": f"Bearer {token}"},
)
print(resp.json())

Response 200 OK

{
  "kit_id": "BS1-ABC12",
  "status": "Sample Received",
  "description": "Lab has received and logged the sample",
  "date": "2025-07-10T14:22:00Z"
}

The status values match those listed in Kit / Sample Status Updates below.

Error Cases

Get Order Status

Look up the current fulfilment status of an order.

Request Headers

Example Request

curl https://app.biomesight.com/api/v1/status/order/ORD-20250615-001 \
  -H "Authorization: Bearer eyJhbGciOi..."

import requests

resp = requests.get(
    "https://app.biomesight.com/api/v1/status/order/ORD-20250615-001",
    headers={"Authorization": f"Bearer {token}"},
)
print(resp.json())

Response 200 OK

{
  "order_id": "ORD-20250615-001",
  "status": "Delivered",
  "description": "Kit has been delivered",
  "date": "2025-06-20T09:15:00Z"
}

The status values match those listed in Order Status Updates below.

Error Cases

Status Webhooks

Biomesight pushes status updates to your endpoint as orders and samples progress through the fulfilment and lab pipeline. You provide a webhook URL during onboarding and we send authenticated POST requests to it whenever a status changes.

Webhook Payload

{
  "order_id": "ORD-20250615-001",   // for order updates
  "kit_id": "BS1-ABC12",              // for kit/sample updates
  "status": "Sample Received",
  "description": "Lab received sample",
  "date": "2025-07-10T14:22:00Z"
}

Webhook requests include an Authorization: Bearer header using OAuth credentials you provide to us, so you can verify the sender.

Kit / Sample Status Updates

These statuses are pushed as a sample moves through the lab pipeline: