Sandbox

The sandbox lets you build and test the entire integration without touching production data. It is not a separate host: you send requests to the same base URL with a vr_test_ key.

https://vitarelay.com/api/public/v1

What a test key does

Nothing real is created. No patients, no intakes, no orders are written to production tables.
No card is ever charged. Payment is simulated.
Validation is identical to live. Same required fields, same request and response shapes, same error codes, same idempotency behavior.
Responses are synthetic. Objects come back with sandbox identifiers and a "sandbox": true marker.

Synthetic identifiers

Object	Sandbox id
Patient	`sandbox_pat_…`
Intake	`sandbox_int_…`
Order	`sandbox_ord_…`

{
  "data": {
    "id": "sandbox_pat_9f2c41d6",
    "external_patient_id": "clinic-patient-001",
    "sandbox": true
  }
}

In live traffic these ids are UUIDs. Sandbox ids are the only non-UUID identifiers the API returns.

When referencing a sandbox patient from an intake or order, pass either the external_patient_id you supplied or the returned sandbox_pat_… id. Both resolve.

Simulated lifecycle

Sandbox objects advance on a timer, a few seconds apart, and each transition enqueues the same webhook event your live integration will receive — marked sandbox: true in the payload.

You create	Simulated events
Intake	`intake.reviewed`
Order	`order.paid` → `order.shipped` → `order.delivered`

Webhooks only arrive if the clinic has a webhook endpoint configured and subscribed to those events. Endpoints are configured by a VitaRelay admin in the dashboard, not through the API. See Webhooks Overview.

Run the full loop in sandbox

Get a test key

Ask your VitaRelay representative for a vr_test_ key with patients:write, intakes:write, and orders:write. See API Keys.

Create a patient

curl https://vitarelay.com/api/public/v1/patients \
  -H "Authorization: Bearer vr_test_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_patient_id": "clinic-patient-001",
    "first_name": "Jane",
    "last_name": "Smith",
    "dob": "1985-04-12",
    "email": "jane.smith@example.com",
    "phone": "+18135550100"
  }'

Returns 201 with data.id = sandbox_pat_… and data.sandbox = true.

Submit an intake

curl https://vitarelay.com/api/public/v1/intakes \
  -H "Authorization: Bearer vr_test_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_intake_id": "clinic-intake-001",
    "external_patient_id": "clinic-patient-001",
    "category": "weight_management",
    "responses": {
      "chief_complaint": "Weight management",
      "current_medications": [],
      "allergies": ["penicillin"]
    }
  }'

A few seconds later, an intake.reviewed event is delivered to your configured endpoint.

Place an order

curl https://vitarelay.com/api/public/v1/orders \
  -H "Authorization: Bearer vr_test_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "external_order_id": "clinic-order-001",
    "external_patient_id": "clinic-patient-001",
    "items": [
      { "product_id": "6f1a2b3c-4d5e-4f60-8a71-9b0c1d2e3f40", "quantity": 1 }
    ]
  }'

Returns 201 with data.id = sandbox_ord_…. No charge is attempted.

Watch the order events arrive

Your endpoint receives order.paid, then order.shipped, then order.delivered, each signed exactly like a live event and each carrying sandbox: true.

Idempotency in sandbox

Idempotency works the same way as in live. Replaying a request with the same external_patient_id, external_intake_id, or external_order_id and the same body returns the original sandbox object with 200 instead of 201. Reusing an external id with a different body returns 409 duplicate_request.

Errors in sandbox

Error codes and statuses are identical to live — including validation_failed, product_not_found, insufficient_scope, and rate_limited. See Errors.

Sandbox and live never intersect. A vr_test_ key cannot read or modify production records, and objects created in the sandbox are invisible to vr_live_ keys.

Getting Started

Webhooks

Guides

Sandbox

Sandbox

What a test key does

Synthetic identifiers

Simulated lifecycle

Run the full loop in sandbox

Idempotency in sandbox

Errors in sandbox

​Sandbox

​What a test key does

​Synthetic identifiers

​Simulated lifecycle

​Run the full loop in sandbox

​Idempotency in sandbox

​Errors in sandbox

Sandbox

What a test key does

Synthetic identifiers

Simulated lifecycle

Run the full loop in sandbox

Idempotency in sandbox

Errors in sandbox