Orders

Order management for drug tests, physicals, and other occupational health services. Create orders, check status, and retrieve results.

10 endpoints

Guide

The Orders API is the core of BlueHive — it handles creating, tracking, and completing occupational health service orders. Orders can be created for individual consumers (self-pay), employer-sponsored employees, or in bulk for multiple employees. The API supports the full order lifecycle from creation through results delivery.

Order Types

BlueHive supports three order creation patterns, each requiring a different set of fields:

  • Consumer (self-pay): Provide person details, services, providerId, and paymentMethod. Used when an individual orders directly.
  • Employer-sponsored (single): Provide employeeId, employerId, and services. The employer covers the cost.
  • Bulk orders: Provide employeeIds (array), employerId, servicesIds, and providersIds. Creates orders for multiple employees at once.

Creating an Employer-Sponsored Order

The most common workflow: an employer sends an employee for a drug test, physical, or other occupational health service. This creates the order and triggers notifications to the employee and provider.

Create employer order
Send an employee for a drug test
const response = await fetch('https://api.bluehive.com/v1/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    employeeId: '64f1a2b3c4d5e6f7a8b9c0d1',
    employerId: '64f1a2b3c4d5e6f7a8b9c0d2',
    services: [
      { _id: 'svc_drug_test_10panel', quantity: 1 },
      { _id: 'svc_physical_dot', quantity: 1 }
    ],
    providerId: '64f1a2b3c4d5e6f7a8b9c0d3',
    dueDate: '2026-04-15T00:00:00.000Z',
    priority: 'normal',
    metadata: {
      requisitionNumber: 'REQ-2026-0042',
      department: 'Transportation'
    }
  })
});

const order = await response.json();
console.log('Order ID:', order.orderId);
console.log('Order Number:', order.orderNumber);
// The employee and provider will receive email notifications

Order Lifecycle

Orders progress through a defined set of statuses. Understanding this flow is key to building integrations:

  • order_sent — Order created and sent to the provider
  • order_accepted — Provider accepted the order
  • order_refused — Provider declined the order (rare)
  • employee_confirmed — Employee confirmed their appointment
  • order_fulfilled — Services have been performed
  • order_complete — Results posted and order finalized

Split Orders

When services in a single order are mapped to different providers, the API automatically splits the order. You will receive an array of order results, each with its own orderId, orderNumber, and providerId.

Handling split orders
Check for split order responses
const result = await response.json();

if (result.status === 'split') {
  // Order was split across multiple providers
  console.log('Split into', result.orderResults.length, 'orders:');
  for (const order of result.orderResults) {
    console.log(`  Order ${order.orderNumber} → Provider ${order.providerId}`);
  }
} else {
  // Single order
  console.log('Order:', result.orderNumber);
}

// Check for unavailable services
if (result.unavailableServices?.length) {
  console.warn('Some services were unavailable:');
  for (const svc of result.unavailableServices) {
    console.warn(`  ${svc.serviceName}: ${svc.reason}`);
  }
}

Scheduling Appointments

After creating an order, schedule an appointment at the provider. This sends an HL7 SIU^S12 message to the provider's EHR system to book the slot.

Schedule an appointment
Book a clinic appointment for an order
await fetch('https://api.bluehive.com/v1/orders/ORD123/schedule-appointment', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    appointment: {
      type: 'appointment',
      dateTime: '2026-04-15T10:30:00.000Z',
      date: '2026-04-15',
      time: '10:30'
    },
    orderAccessCode: 'AC-98765'
  })
});
// This triggers an HL7 SIU^S12 message to the provider's EHR

Retrieving Results

Once services are performed, results can be retrieved through the results endpoint. Results include status, result text, timestamps, and attached file references. Use pagination and filters for large result sets.

Get order results
Retrieve test results for an order
# Get all results for an order
curl "https://api.bluehive.com/v1/orders/ORD123/results" \
  -H "Authorization: ApiKey YOUR_API_KEY"

# Filter by service and status
curl "https://api.bluehive.com/v1/orders/ORD123/results?serviceId=svc_drug_test&status=completed" \
  -H "Authorization: ApiKey YOUR_API_KEY"

# Response structure:
# {
#   "meta": { "orderId": "ORD123", "orderNumber": "BH-2026-0042", ... },
#   "services": [
#     {
#       "serviceId": "svc_drug_test",
#       "status": "completed",
#       "result": "negative",
#       "resultsPosted": "2026-04-16T14:30:00.000Z",
#       "fileIds": ["file_abc123"]
#     }
#   ]
# }

Searching Order Items

The order items search endpoint provides powerful filtering across all orders. Use it to build dashboards, generate reports, or find specific orders by various criteria.

Search order items
Find orders with advanced filtering
# Search by employer and date range
curl "https://api.bluehive.com/v1/orderItems?employerId=EMP123&since=2026-01-01T00:00:00Z&until=2026-03-31T23:59:59Z&pageSize=25" \
  -H "Authorization: ApiKey YOUR_API_KEY"

# Search by order access code
curl "https://api.bluehive.com/v1/orderItems?orderAccessCode=AC-98765" \
  -H "Authorization: ApiKey YOUR_API_KEY"

# Partial ID search
curl "https://api.bluehive.com/v1/orderItems?orderNumberContains=2026-004" \
  -H "Authorization: ApiKey YOUR_API_KEY"
Chat with Bea