Sandbox Testing
The sandbox lets you build and test your SiPhox integration against the same API and the same base URL as production (https://connect.siphoxhealth.com), without creating real orders. Sandbox mode is a property of the API token you authenticate with, not a per-request flag: a request made with your sandbox token can only ever create and read mock data, and can never reach fulfillment, the lab, or your credit balance.
There is no separate sandbox host or staging deployment. You call the same endpoints at https://connect.siphoxhealth.com; the token you send decides whether the request is live or sandboxed.
The per-request isTestOrder flag on the production token is deprecated in favor of dedicated sandbox tokens. A production-token request that still sends it continues to work today, but returns a Deprecation response header pointing here: that's your signal to finish migrating. After the deprecation window closes, isTestOrder: true on a production token will be rejected with 400. Move all test order creation onto your sandbox token instead; you won't need the flag there, since a sandbox token always operates in test mode.
Get your sandbox API token
Log in to the admin dashboard at https://admin.siphoxhealth.com and open the API Integration section on the main page. Alongside your live token you'll find a Sandbox API token: generate one if you don't have it yet, then copy it. Sandbox tokens are prefixed sk_sandbox_ so they're easy to tell apart from your live token.
You can regenerate the sandbox token at any time; the previous token stops working immediately.
Authentication
Send the sandbox token exactly like your live token, in the Authorization header:
{
"Authorization": "Token sk_sandbox_29a79b15684970aid1bfc6dfab25"
}
Every endpoint under the live API works with the sandbox token. The difference is entirely in what happens behind the scenes:
| With a live token | With a sandbox token |
|---|---|
| Orders ship real kits | Orders create mock kits (IDs prefixed SB_, orders SB_O) |
| Credits are deducted / payment is charged | Nothing is charged, no credits are used |
| Kit lifecycle is driven by real shipping & lab events | You drive the lifecycle yourself via the sandbox endpoints below |
| Reads return your real customers, kits, and reports | Reads return only your sandbox customers, kits, and reports |
| Webhooks fire on real events | Webhooks fire on the transitions you simulate, delivered only to your sandbox webhook URLs |
| Emails are sent to your customers | Emails are sent only to your sandbox override address, or not at all (see below) |
Sandbox and live data are fully isolated. A sandbox token can never read real customers, kits, or reports, and a live token never sees sandbox items. Build against the sandbox freely; you cannot touch production data with it.
Sandbox email delivery
By default, the sandbox sends no emails: driving a mock kit through its lifecycle will not email anyone. In the admin dashboard's sandbox page you can set a sandbox email override: when set, every email the sandbox would send (registration, results-ready, etc.) is delivered to that single address instead, so you can inspect them yourself. Leave it blank to suppress sandbox emails entirely.
A typical test run
1. Create a sandbox order
Call the normal order endpoint with your sandbox token. It returns a mock order and kit instead of shipping anything.
curl -X POST https://connect.siphoxhealth.com/api/v1/create-order
-H "Authorization: Token sk_sandbox_..."
-H "Content-Type: application/json"
-d '{
"recipient": {
"first_name": "Jordan",
"last_name": "Reyes",
"email": "jordan.reyes@example.com",
"address": { "street1": "123 Main St", "city": "Boston", "state": "MA", "zip": "02101", "country": "US" }
},
"kit_types": [{ "kitType": "CORE_BLOOD_PANEL", "quantity": 1 }]
}'
2. List your sandbox kits
curl https://connect.siphoxhealth.com/api/v1/sandbox/kits
-H "Authorization: Token sk_sandbox_..."
Returns every mock kit, each with its kitID, orderID, kitStatus, and sampleStatus.
3. Drive the kit through its lifecycle
Use /simulate to jump a kit straight to a milestone, or /advance for fine-grained control over the exact status.
# Jump straight to a resulted report
curl -X POST https://connect.siphoxhealth.com/api/v1/sandbox/kits/SB_SPOT27A5D0C3/simulate
-H "Authorization: Token sk_sandbox_..."
-H "Content-Type: application/json"
-d '{
"scenario": "resulted",
"metadata": {
"email": "jordan.reyes@example.com",
"firstName": "Jordan",
"lastName": "Reyes",
"gender": "M",
"dateOfBirth": "1990-01-15"
}
}'
Each transition fires the same webhook your integration would receive in production, so you can verify your webhook handling against real payloads. Sandbox events deliver only to the sandbox webhook URL(s) configured in the dashboard's API section (separate from your production URLs), and are signed with your sandbox token. The mock report is generated from the kit's panel definition, filtered to the registrant's gender: the same markers a real report for that kit type would contain.
Advancing a kit to registered or beyond requires registration metadata (email, firstName, lastName, gender, dateOfBirth), unless the kit is already registered. Without it the call returns 400.
Happy-path scenarios (/simulate)
scenario | Drives the kit to |
|---|---|
delivered | Kit delivered to the customer |
registered | Kit registered |
collected | Sample collected |
resulted | Sample resulted; a mock report is generated |
Exception scenarios
Real kits sometimes get stuck. You can simulate those terminal states too, each a one-way branch that mirrors a kit/sample stuck in a carrier or lab exception:
scenario | Simulates |
|---|---|
kit_delivery_exception | The kit hit a delivery exception in transit to the customer |
sample_delivery_exception | The sample hit a delivery exception on its way to the lab |
rejected | The lab rejected the sample (e.g. hemolysis / QNS); no report is produced |
4. Read the results
Once a kit is resulted, fetch the report through the same read endpoints you use in production, e.g. GET /api/v1/customers/{id}/reports/{reportID}. With a sandbox token you can only read sandbox customers and reports.
5. Clean up
Delete a single sandbox order, or wipe all sandbox data for your business. Live data is never affected.
# Delete one sandbox order and its mock kits
curl -X DELETE https://connect.siphoxhealth.com/api/v1/sandbox/orders/SB_O12345ABC
-H "Authorization: Token sk_sandbox_..."
# Reset: remove ALL sandbox orders, kits, reports, and webhook history
curl -X POST https://connect.siphoxhealth.com/api/v1/sandbox/reset
-H "Authorization: Token sk_sandbox_..."
Sandbox endpoint reference
All sandbox endpoints require a sandbox token; calling them with a live token returns 403.
| Method & path | Purpose |
|---|---|
POST /api/v1/sandbox/kits/{kitID}/advance | Advance a mock kit to an explicit lifecycle status |
POST /api/v1/sandbox/kits/{kitID}/simulate | Jump a mock kit to a named scenario |
GET /api/v1/sandbox/kits | List all mock kits for your business |
DELETE /api/v1/sandbox/orders/{orderID} | Delete a sandbox order and its mock kits |
POST /api/v1/sandbox/reset | Delete all sandbox data for your business |
/advance statuses: kit_preparing, kit_in_transit, kit_delivered, kit_delivery_exception, kit_registered, sample_collected, sample_in_transit, sample_delivery_exception, sample_delivered, sample_rejected, sample_resulted
/simulate scenarios: delivered, registered, collected, resulted, kit_delivery_exception, sample_delivery_exception, rejected
Partial results: when resulting a sandbox sample you can also select which markers to result, to exercise the partial-results path (some markers resulted, others still pending) instead of the all-at-once case.
Full API reference
Every endpoint, request schema, and response shape is documented in the interactive API reference. Authorize it with your sandbox token to try calls live: