Logo
/
/
Login
← Back to Blog
clients

Introducing the FloatR API and Webhooks

November 17, 2026

10 minutes read

Connect FloatR to the systems your lab already runs on, and let them work together.

Your lab doesn't run on FloatR alone. Schedules start in your LIS, your scheduling tool or a spreadsheet. Your people are in an HR system, your training is in an LMS, and hours end up in finance and your BI dashboards. Until now FloatR sat beside all of that, and someone on your team carried information between them by hand.
The FloatR API and webhooks connect them.
  • The API lets your systems do what your team does in the lab portal: post tasks, approve claims, manage your network, add and correct time cards, and pull reports.
  • Webhooks work the other way round. When a FloatR claims a task, drops one, passes a training or clocks out, FloatR tells your systems within seconds.

What's included

The API lives at https://api.floatr.io/api/v1 and comes in four parts. FloatR switches on the parts your lab needs.
Part
What your systems can do
Schedule
Locations, jobs, lists and tags. Post, change, publish and cancel tasks. Approve or reject claim requests.
Talent pool
Search the FloatRs available for the jobs you subscribe to, by state, address or map area, with filters for experience, interview score and background checks.
Network & training
Your roster, with each FloatR's hours, rating and reliability. Approve and block FloatRs, and organise them into lists. Create trainings and pull results.
Shifts & reports
Time cards by invoice period. Add and correct shifts, decide on FloatRs' change requests, and download the shift report as CSV.
Webhooks cover 29 events across Schedule, Network & training, and Shifts & reports.
API keys are created and revoked by your managers in the portal. Like your team members, each key has a role, manager or user. It can also be read-only, and set to expire.
Docs for every endpoint and event are in the portal under Help & docs, with request and response examples.

Getting set up

  1. Ask your FloatR account manager to switch on the API for your lab, and the parts you need.
  1. Create a key. In the portal, open the profile menu and choose API & webhooks. Give the key a name, choose its role, and decide whether it's read-only and when it expires.
  1. Copy it. It's shown once. Send it as a bearer token with every request:
curl https://api.floatr.io/api/v1/locations \ -H "Authorization: Bearer $FLOATR_API_KEY"
The JavaScript examples below share one small helper:
const API = "https://api.floatr.io/api/v1"; async function floatr(path, { method = "GET", body } = {}) { const res = await fetch(API + path, { method, headers: { Authorization: `Bearer ${process.env.FLOATR_API_KEY}`, "Content-Type": "application/json", }, body: body && JSON.stringify(body), }); if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`); return res.json(); }

Twelve things you can build

1. Post tasks from the system that knows you need them

Your scheduling tool or LIS is the first to know when a site will be short. Let it post the task, instead of waiting for someone to retype it.
curl -X POST https://api.floatr.io/api/v1/tasks \ -H "Authorization: Bearer $FLOATR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "location": "loc_01HN3DBTEHTPBPN70TKMXP13BD", "job": "job_01HBM5WBTS1B3MS68WDQQZ78DW", "starts": "2026-12-01 07:30:00", "ends": "2026-12-01 11:30:00", "status": "published", "name": "Morning draws", "min_star_rating": 4.5, "proximity_radius_miles": 30 }'
Times are local to the location. You can target a task posted through the API the same ways as in the portal: to your lists, by required tags, distance or minimum rating, or assigned to one FloatR. Post a draft for someone to review, then publish it with PATCH /tasks/:id. Send {"status": "deleted"} to cancel one, and the FloatRs on it are told.

2. Keep your locations in step with your own

Store your own ID for each site in external_id. Your system can then find any location by that ID, and create or update it.
async function syncSite(site) { const fields = { name: site.name, address1: site.street, city: site.city, state: site.state, zip: site.zip, timezone: site.timezone, details: site.arrivalNotes, // parking and check-in, shown to FloatRs external_id: site.code, }; const { locations } = await floatr( `/locations?external_id=${encodeURIComponent(site.code)}`, ); if (locations.length) { await floatr(`/locations/${locations[0].id}`, { method: "PATCH", body: fields }); } else { await floatr("/locations", { method: "POST", body: fields }); } }
Run it whenever a site opens or changes, and FloatRs always have the right address, timezone and arrival notes.

3. Approve claim requests by your own rules

On a task that needs approval, a FloatR's claim waits in your queue. A webhook and one API call let your own rules decide: your credential tracker, a site's preferred list, or the FloatR's record with you from GET /network/:user_id.
// in your webhook endpoint (see "Verifying webhooks" below) if (event.type === "task.claim_requested") { const { task, floatr: who } = event.data; const ok = await yourRules.shouldApprove(who, task); await floatr(`/tasks/${task.id}/requests/${who.id}/${ok ? "approve" : "reject"}`, { method: "POST", }); }
The FloatR hears back straight away, instead of whenever someone next checks the queue.

4. A live coverage feed for your team

Send task.claimed, task.claim_approved and task.dropped to a Slack or Teams channel, and everyone sees coverage change as it happens. Better still, alert the site lead when someone drops a task that starts soon:
if (event.type === "task.dropped") { const { task, floatr: who, reason } = event.data; await slack.post( `${who.first_name} ${who.last_name} came off "${task.name}" ` + `(${task.starts}, ${task.timezone}). Reason: ${reason || "none given"}`, ); }
was in the event tells you whether they'd claimed the task, been assigned it, or withdrew a claim request.

5. Send each week's hours to finance

Shifts are grouped into weekly invoice periods, which lock on the Monday after they end. Once a period is locked, pull its shifts to check your FloatR invoice, charge each site's hours to its cost centre, or bill your own clients for the work.
const { shifts, isLocked } = await floatr(`/shifts?period=${period.id}`); if (!isLocked) return; // wait until the time cards are final for (const s of shifts) { await finance.recordHours({ costCentre: costCentres[s.location.id], floatr: `${s.user.first_name} ${s.user.last_name}`, job: s.job.name, starts: s.lab_starts_suggested ?? s.starts, // your team's corrections win ends: s.lab_ends_suggested ?? s.ends, timezone: s.timezone, }); }
GET /shifts/periods lists the periods. To handle shifts as they happen instead, listen for shift.created and shift.updated.

6. Put the shift report in your BI tool

GET /reports/shifts returns up to 90 days of worked shifts as CSV, one row per shift, with the FloatR, location, job, hours and rating. Each row includes the location's external_id, so it joins straight onto your own data. Point Power BI, Tableau, Looker or a scheduled script at it with a read-only manager key.
curl "https://api.floatr.io/api/v1/reports/shifts?starts=2026-11-01&ends=2026-11-30&headers=true" \ -H "Authorization: Bearer $FLOATR_API_KEY" -o shifts.csv

7. Review time card changes where you review hours

When a FloatR asks to change a shift's times, you get shift.change_requested. Show it in the tool your supervisors already use, and send their decision back with POST /shifts/:id/requests/approve or /reject. Your own corrections and ratings go through PATCH /shifts/:id, and you can add a shift for a FloatR who worked without clocking in with POST /shifts.

8. Keep training in step with your LMS

Create trainings from your learning system, quiz and all:
curl -X POST https://api.floatr.io/api/v1/trainings \ -H "Authorization: Bearer $FLOATR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Arriving at Denver Draw Station", "type": "video", "video_url": "https://lms.example.com/videos/denver-orientation.mp4", "jobs": ["job_01HBM5WBTS1B3MS68WDQQZ78DW"], "is_active": true, "is_mandatory": true, "passing_score": 80, "max_attempts": 3, "quiz_data": { "questions": [ { "question": "Where do completed specimens go before courier pickup?", "options": ["The front desk", "The specimen refrigerator in the draw room", "The lockbox outside"], "correct_answer": 1 } ] } }'
Videos and PDFs can be uploaded to a training too. Then record each pass in your LMS as it happens:
if (event.type === "training.passed") { const { training, floatr: who, result } = event.data; await lms.recordCompletion(who.id, training.id, result.quiz_score); }
GET /network/:user_id/trainings gives you one FloatR's full record whenever you need it. There's more on how training works in Training: Get FloatRs Ready Before They Walk In.

9. Keep your network in step with HR

Approve your regulars from the roster you already keep, with a note your team can read, using POST /network/:user_id/approve. Block someone from your incident system with POST /network/:user_id/block, which also takes them off your upcoming tasks. And keep lists such as Pediatric certified or Spanish speakers matched to your own records, then post tasks that only those lists can claim.

10. Feed candidates into your recruiting pipeline

If you subscribe to a job's talent pool, search it from your own ATS or CRM: by state or around an address, filtered by experience, interview and résumé scores, skills, or a current background check.
curl "https://api.floatr.io/api/v1/pool/users?job=job_01HBM5WBTS1B3MS68WDQQZ78DW&address=Denver%2C%20CO&backgroundChecked=true&interviewScore=70,100" \ -H "Authorization: Bearer $FLOATR_API_KEY"

11. Build your own workforce dashboard

GET /network returns every FloatR who works with you, with their hours for each of the last 12 weeks, lifetime hours, your rating, upcoming tasks and call-outs. Sort by recent_hours to see your core team, or by call_outs to see who needs a conversation, and chart them beside your own staff.

12. Let an AI assistant write the integration

Every docs page in the portal has a Copy page button, and the docs home has Copy all docs. Paste them into Claude, ChatGPT or whatever coding assistant your developers use, and describe what you want: "When a FloatR drops a task that starts in the next 24 hours, text the site lead." The docs spell out every endpoint, field, event and error code, so an assistant has what it needs.

Webhooks, in more detail

Create a webhook in the portal under API & webhooks → Webhooks: your endpoint's URL, and the events to send it. You choose each event by name, so an event FloatR adds later never reaches your endpoint until you choose it.
Section
Events
Schedule
location.created, location.updated, location.deleted, task.created, task.updated, task.claimed, task.claim_requested, task.claim_approved, task.claim_rejected, task.dropped
Network & training
floatr.approved, floatr.unapproved, floatr.blocked, floatr.unblocked, segment.created, segment.deleted, segment.member_added, segment.member_removed, training.created, training.updated, training.deleted, training.passed, training.failed
Shifts & reports
shift.created, shift.updated, shift.deleted, shift.change_requested, shift.change_approved, shift.change_rejected
Each event is a JSON POST:
{ "id": "evt_01JD3W6Y7RZ8KQ4N2M5P9TXV1B", "type": "task.claimed", "created_at": "2026-11-17T14:02:11.482Z", "triggered_by": { "type": "floatr", "id": "usr_…" }, "data": { "task": { "id": "tsk_…", "name": "Morning draws", "starts": "2026-12-01 07:30:00", "timezone": "America/Denver", "…": "…" }, "floatr": { "id": "usr_…", "first_name": "Jordan", "last_name": "Lee" } } }
  • triggered_by says who made the change: one of your API keys, someone on your team, a FloatR, or FloatR itself. Your system can skip the changes it made.
  • id is the same on every retry, so you can ignore an event you've already handled.
Verifying webhooks. Every request is signed with HMAC-SHA256 using your webhook's secret, in the FloatR-Signature header. Check it before trusting a request:
const crypto = require("node:crypto"); const express = require("express"); const app = express(); app.post("/floatr", express.raw({ type: "application/json" }), async (req, res) => { const sig = Object.fromEntries( (req.get("FloatR-Signature") || "").split(",").map((p) => p.split("=")), ); const expected = crypto .createHmac("sha256", process.env.FLOATR_WEBHOOK_SECRET) .update(`${sig.t}.${req.body}`) .digest("hex"); const valid = sig.v1?.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig.v1), Buffer.from(expected)) && Math.abs(Date.now() / 1000 - Number(sig.t)) < 300; if (!valid) return res.sendStatus(400); res.sendStatus(200); // answer first, then do the work const event = JSON.parse(req.body); // examples 3, 4 and 8 go here });
If your endpoint goes down. Anything other than a 2xx is retried after 1 minute, 5 minutes, 30 minutes, then 2, 6, 12 and 24 hours. If nothing gets through for that long, FloatR turns the webhook off and emails the manager who set it up. Every delivery is kept for 30 days with the request and your endpoint's response, and you can resend any of them once you're back up. Send test event checks an endpoint without waiting for something to happen.

Built to be safe

  • Keys only see your lab. A key can never reach another lab's data, and a user key can't reach what only managers can.
  • Read-only keys can call GET endpoints and nothing else, which is all reporting and dashboards need.
  • Keys are shown once and stored hashed. Revoke one in the portal and it stops working straight away, or give it an expiry date.
  • Your FloatR account manager controls what's switched on, part by part. If scheduling is turned off for your lab, the Schedule and Network & training parts of the API turn off with it.
  • Webhooks only go to public https:// addresses, and each request is signed so your endpoint knows it came from FloatR.
  • Each key can make 300 requests a minute, so one runaway script can't affect anything else.

Get started

Ask your FloatR account manager to switch the API on for your lab. Then find keys and webhooks under API & webhooks in the portal's profile menu, and the full reference under Help & docs.

Enjoyed this post? There's more where that came from.

FloatR Logo

FloatR is the workforce operating system healthcare organizations use to source, schedule, and deploy clinical staff — without the agency.

133 C New York Avenue
#120
Huntington, NY 11743

Follow Us

Platform

The PlatformClientAgentPool

© 2026 FloatR Inc. All rights reserved.

Terms of Use & Privacy Policy
Loading...