Employees

Employee management endpoints. Create, update, and retrieve employee records associated with employer accounts.

7 endpoints

Guide

Employee endpoints handle the full lifecycle of employee records — from creation and updates to linking with user accounts. Employees are always associated with an employer and are the subjects of orders and test results.

Creating an Employee

Create employees by providing personal information and linking them to an employer. At minimum, you need first name, last name, and email. Include address, phone numbers, and date of birth for a complete profile that enables HL7 messaging and order processing.

Create an employee
Register a new employee under an employer
const response = await fetch('https://api.bluehive.com/v1/employees', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstName: 'Jane',
    lastName: 'Smith',
    email: '[email protected]',
    dob: '1990-05-15',
    employer_id: '64f1a2b3c4d5e6f7a8b9c0d1',
    address: {
      street1: '789 Oak Lane',
      city: 'Detroit',
      state: 'MI',
      postalCode: '48202'
    },
    phone: [
      { number: '3135559876', type: 'Cell' }
    ],
    departments: ['Warehouse'],
    activeAccount: 'Active'
  })
});

const result = await response.json();
console.log('Employee ID:', result.employeeId);

Listing Employees

Retrieve all employees for a given employer with pagination support. Use limit and offset parameters to page through large employee rosters.

List employees with pagination
Get employees for an employer
# Get first 50 employees
curl "https://api.bluehive.com/v1/employees?employerId=64f1a2b3c4d5e6f7a8b9c0d1&limit=50&offset=0" \
  -H "Authorization: ApiKey YOUR_API_KEY"

# Get next page
curl "https://api.bluehive.com/v1/employees?employerId=64f1a2b3c4d5e6f7a8b9c0d1&limit=50&offset=50" \
  -H "Authorization: ApiKey YOUR_API_KEY"

Extended Fields

Use extended fields to store custom metadata on employees beyond the standard fields. This is useful for tracking employee-specific data like badge numbers, cost centers, or custom identifiers from your HRIS system.

Employee with extended fields
Store custom metadata on an employee
{
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "employer_id": "64f1a2b3c4d5e6f7a8b9c0d1",
  "extendedFields": [
    { "name": "Badge Number", "value": "EMP-4521" },
    { "name": "Cost Center", "value": "CC-7890" },
    { "name": "HRIS ID", "value": "HR-123456" }
  ]
}

Linking to User Accounts

Link employees to platform user accounts to enable self-service features. Once linked, employees can view their own orders, confirm appointments, and access results through the BlueHive portal.

Link employee to user
Associate an employee with a user account
curl -X POST https://api.bluehive.com/v1/employees/link-user \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "employeeId": "64f1a2b3c4d5e6f7a8b9c0d1",
    "userId": "user_abc123",
    "role": ["user"]
  }'
Chat with Bea