HarmonyWFM REST API

1. What you get, and what you build

2. Setup checklist

3. Base URL and authentication

Every key is bound to one company. There is no tenant parameter — the key determines which company's data you see, and cross-company access is impossible.

Base URL   https://harmonywfm.com/api/public/v1
Header     Authorization: Bearer hwfm_xxxxxxxxxxxxxxxxxxxxxxxx
Header     Content-Type: application/json   (writes only)

curl -H "Authorization: Bearer hwfm_YOUR_KEY" \
  "https://harmonywfm.com/api/public/v1/config"

• TLS is required; plain HTTP is rejected.
• Scope enforcement: GET needs read; POST/PATCH/DELETE need write.
• Revoking a key in the Integrations tab takes effect immediately.
• Last-used timestamps are recorded so unused keys can be spotted and retired.

4. Endpoints

5. Configuration resources by module

Resources marked with a module are only reachable when that module is active for the company; otherwise the API returns 403. Singleton resources hold one row per company and are updated with PATCH /config/:resource (no id).

6. Request and response shapes

# List with filters, paging and ordering
GET /api/public/v1/config/locations?is_active=true&limit=50&offset=0&order=name

{ "resource": "locations", "count": 2, "data": [ { "id": "…", "name": "Detroit Plant", … } ] }

# Create
POST /api/public/v1/config/departments
{ "name": "Maintenance", "code": "MNT" }
→ 201 { "resource": "departments", "data": { "id": "…", … } }

# Update a singleton
PATCH /api/public/v1/config/points-settings
{ "late_points": 0.5, "ncns_points": 4 }

# New hire
POST /api/public/v1/employees
{ "first_name": "Dana", "last_name": "Reyes", "email": "dana@acme.com",
  "hire_date": "2026-09-01", "location_id": "…", "job_id": "…",
  "pay_type": "hourly", "hourly_rate": 24.5 }

Fields id, company_id, created_at and updated_at are managed by HarmonyWFM and ignored if sent. Dates use YYYY-MM-DD; timestamps are ISO-8601 UTC. Punch and shift times are stored in UTC and displayed in the employee's location timezone.

7. Webhooks

Add an endpoint under Settings → Integrations → Webhooks, pick events, and store the signing secret. Each delivery is a POST with a JSON body and these headers: x-harmony-event, x-harmony-timestamp (unix seconds) and x-harmony-signature.

// Node — verify the signature before trusting the payload
import crypto from "node:crypto";

app.post("/hooks/harmony", express.raw({ type: "*/*" }), (req, res) => {
  const ts = req.header("x-harmony-timestamp");
  const sig = req.header("x-harmony-signature");
  const body = req.body.toString("utf8");
  const expected = crypto
    .createHmac("sha256", process.env.HARMONY_WEBHOOK_SECRET)
    .update(`${ts}.${body}`)
    .digest("hex");

  if (!sig || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
    return res.status(401).end();
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.status(400).end();

  const { event, company_id, sent_at, data } = JSON.parse(body);
  // enqueue and return quickly
  res.status(200).end();
});

• Respond within 10 seconds with a 2xx; anything else is logged as a failure.
• Deliveries are logged in the Integrations tab with status, duration and error.
• Use the Send test button to fire a signed ping while you build.
• Handle duplicates idempotently — treat the payload id as the dedupe key.

8. Operating guidance

• Page large reads with limit/offset; keep batches ≤ 500.
• Retry 5xx and network failures with exponential backoff; never retry 4xx blindly.
• Sync incrementally where possible — filter on updated_at or a date range instead of pulling everything each run.
• Write to payroll-relevant objects (punches, timecards) before the pay period locks; locked periods reject edits.
• Use separate keys per integration so one can be revoked without breaking others.
• Rotate keys on a schedule and whenever staff with access leave.