Build on BimHR Solutions

Employees

List, create, fetch, and update employee records. The API key's company_id becomes the implicit tenant scope — a key issued for company A can NEVER read or write company B's employees.

Leave

List leave requests and submit new ones on behalf of an employee. New requests are created with status='pending' so they flow through your normal approval chain.

Payroll

List payroll runs (metadata only — never individual payslip lines). Use the in-app UI to drill into a specific run.

Webhooks

List webhook delivery history for the API key's company. Useful for integration monitoring.

Event types

An endpoint with an empty events array subscribes to ALL event types.

Payload reference

The POST body is a JSON object with the following shape:

{
  "event": "leave.approved",
  "delivered_at": "2026-07-28T12:34:56.789Z",
  "delivery_id": "uuid",
  "payload": {
    "requestId": "uuid",
    "employeeId": "uuid"
  }
}

Verifying the signature

Every POST includes an X-Webhook-Signatureheader containing the hex-encoded HMAC-SHA256 of the raw request body, keyed by the endpoint's secret. Verify it before processing:

import { createHmac } from "crypto";

// Read raw body BEFORE any JSON parsing.
const rawBody = await request.text(); // or: request.body in Python
const signature = request.headers.get("X-Webhook-Signature");

const expected = createHmac("sha256", WEBHOOK_SECRET)
  .update(rawBody, "utf8")
  .digest("hex");

if (signature !== expected) {
  return new Response("Invalid signature", { status: 401 });
}

// Signature is valid — safe to parse + act on the payload.
const event = JSON.parse(rawBody);
console.log(event.event, event.payload);

Retry policy

Failed deliveries are retried up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s). After all attempts fail, the delivery is marked failed and the owner can manually retry it from the Webhooks settings tab.

curl

curl -X GET https://your-bimhr-domain.com/api/v1/employees \
  -H "Authorization: Bearer bimhr_live_<your_key>" \
  -H "Accept: application/json"

javascript

const res = await fetch("https://your-bimhr-domain.com/api/v1/employees", {
  method: "GET",
  headers: {
    "Authorization": "Bearer bimhr_live_<your_key>",
    "Accept": "application/json",
  },
});
const data = await res.json();
console.log(data.employees);

python

import requests

res = requests.get(
    "https://your-bimhr-domain.com/api/v1/employees",
    headers={
        "Authorization": "Bearer bimhr_live_<your_key>",
        "Accept": "application/json",
    },
)
print(res.json()["employees"])