Developers
Timerfly API & webhooks
The short answer
Timerfly has a read-only REST API and signed webhooks on the Business plan, and connects to Zapier, Make and n8n without code. Your systems can read attendance, hours, apps, projects and leave as JSON, and get an event the moment someone starts work, an alert fires or leave is approved. Both are included in the 14-day free trial.
At a glance
- Plan
- Business, and every 14-day free trial. Starter and Pro don’t include the API or webhooks.
- API
- REST, JSON over HTTPS, read-only. Version v1.
- Sign-in
- An API key, sent as “Authorization: Bearer tf_…”. Made and revoked by an owner or admin in Settings.
- Data
- People, departments, attendance per day, hours, apps and websites, projects, time entries, leave and holidays, and who’s working now.
- Limits
- 120 requests a minute per key; up to 92 days per request.
- Webhooks
- 7 events, sent as they happen to any public https address, signed with HMAC-SHA256 and retried five times.
- No-code
- Zapier, Make and n8n, through webhooks and their HTTP steps.
Ways to connect
Pick by where the data needs to go. Each link has the exact steps.
- Your own system, CRM or BI
Read attendance, hours, projects and leave with the REST API: Zoho, HubSpot, Power BI, Google Sheets or your own code. API setup guide →
- HR, payroll or a ticketing tool
Get a signed webhook when someone starts work, an alert fires, a timer stops or leave is approved. Webhook reference →
- Zapier, Make or n8n
Point a webhook at their “catch hook” address and use the fields in any of their apps, without code. Zapier guide →
- Slack, Teams, Google Chat, Telegram
Alerts in team chat need no API: they’re built in, on Pro and Business. All integrations →
- Payroll sheets
No developer needed: any dates export to Excel from Reports on every plan, and the monthly payroll Excel (paid days, loss of pay, late marks) is on Pro. Payroll export →
Not built yet: ready-made connectors for Jira, Asana and Google Calendar. Zapier, Make and the API reach most tools meanwhile; if you need one, tell us.
Getting started
- An owner or admin goes to Settings → API & integrations → API keys, names a key after what will use it, and copies it. It’s shown once; keep it like a password.
- Send it on every request:
Authorization: Bearer tf_… - Base address:
https://api.timerfly.com/api/v1 - Call
/meto check the key works.
- Read-only. A key can’t change anything, and reads only its own company.
- Dates are the company’s own days (its timezone), as YYYY-MM-DD. Times are ISO 8601 in UTC. Durations are whole seconds.
- Answers are
{ "data": [...] }, so new fields can be added without breaking your code. Ignore fields you don’t know. - Revoke a key in Settings any time; it stops working at once.
The same steps with pictures are in the help centre: Is there an API?
Endpoints
9 endpoints, all GET, under https://api.timerfly.com/api/v1.
GET /me
The company this key reads: id, name, timezone, workDays, workStart, workEnd. Use it to check a key.
GET /members
Everyone in the company: id, name, email, role (owner, admin, employee), status, department, joinedAt.
| include=deactivated | Also people who were deactivated. |
|---|
GET /departments
Departments: id and name.
GET /days
Attendance and time, one row per person per day.
| from | First day, YYYY-MM-DD (required). |
|---|---|
| to | Last day (default: from). Up to 92 days. |
| memberId | One person only. |
Fields: date, member, status (worked, absent, leave, holiday, day_off, not_started, upcoming, not_joined: before they joined), leaveType, arrivalAt, departureAt, trackedSec, productiveSec, neutralSec, unproductiveSec, idleSec, breakSec, offlineSec, expectedSec, late, leftEarly, effectiveness (%), productivity (%), scheduled { start, end }, location (office, remote, both or null), officeSec, remoteSec
GET /apps
Apps and websites used in a range, most time first: name, category (productive, neutral, unproductive), seconds, people.
| from | Required. |
|---|---|
| to | Optional. |
| memberId | One person only. |
GET /projects
Projects: id, name, status (active, archived), color, createdAt.
GET /time-entries
Time booked to projects (timers and entries added by hand). A running timer has endedAt null.
| from | Required. |
|---|---|
| to | Optional. |
| memberId | One person. |
| projectId | One project. |
Fields: id, member, project, task, startedAt, endedAt, durationSec, note
GET /leave
Leave and holidays overlapping a range (a holiday has member null). Notes are not included: they can be personal.
| from | Required. |
|---|---|
| to | Optional. |
| memberId | One person (plus company holidays). |
Fields: id, member, type (vacation, sick, remote, holiday, other, unpaid), part (full, first_half, second_half, hours), minutes, status (pending, approved, rejected), startDate, endDate
GET /live
Who’s working right now, one row per person.
Fields: member, department, status (working, idle, break, private, offline), currentApp (while working), lastSeenAt, today { arrivalAt, trackedSec, productiveSec, idleSec, late }
Examples
curl
curl https://api.timerfly.com/api/v1/days?from=2026-09-01&to=2026-09-30 \
-H "Authorization: Bearer tf_your_key"JavaScript (Node 18+)
const res = await fetch('https://api.timerfly.com/api/v1/days?from=2026-09-01&to=2026-09-30', {
headers: { Authorization: `Bearer ${process.env.TIMERFLY_KEY}` },
});
const { data } = await res.json();
const absent = data.filter((d) => d.status === 'absent');Python
import os, requests
r = requests.get("https://api.timerfly.com/api/v1/days",
params={"from": "2026-09-01", "to": "2026-09-30"},
headers={"Authorization": f"Bearer {os.environ['TIMERFLY_KEY']}"})
for d in r.json()["data"]:
print(d["date"], d["member"]["name"], d["status"], d["trackedSec"] // 3600, "h")Google Sheets (Apps Script): yesterday’s attendance, every morning
// Google Sheets: Extensions → Apps Script. Put the key in Project Settings → Script properties (TIMERFLY_KEY).
function loadYesterday() {
const key = PropertiesService.getScriptProperties().getProperty('TIMERFLY_KEY');
const day = Utilities.formatDate(new Date(Date.now() - 864e5), 'Asia/Kolkata', 'yyyy-MM-dd');
const res = UrlFetchApp.fetch('https://api.timerfly.com/api/v1/days?from=' + day, { headers: { Authorization: 'Bearer ' + key } });
const rows = JSON.parse(res.getContentText()).data.map((d) =>
[d.date, d.member.name, d.status, d.arrivalAt, d.departureAt, Math.round(d.trackedSec / 36) / 100, d.late]);
if (rows.length) SpreadsheetApp.getActiveSheet().getRange(SpreadsheetApp.getActiveSheet().getLastRow() + 1, 1, rows.length, 7).setValues(rows);
}
// Then Triggers → Add trigger → loadYesterday, time-driven, every day at 6–7 am.Power BI: Get data → Web → Advanced, URL https://api.timerfly.com/api/v1/days?from=…&to=…, and add the header Authorization with Bearer tf_…. Expand data into rows.
Webhooks
In Settings → API & integrations → Webhooks, add an https address and choose the events (none ticked means all of them, including ones added later). Timerfly POSTs each event as it happens.
Events
- day.started
- Someone started work. Their first activity of the day, with the arrival time. (Lateness comes as an alert: alert.created, type late_start.)
- data: member { id, name }, date, arrivalAt
- alert.created
- An alert fired. Late start, idle too long, a long break, overtime, the app not reporting… — the same alerts as in Timerfly.
- data: id, type (late_start, long_idle, unproductive, overtime, device_silent, work_start, work_stop, break_start, break_end, long_break, break_total, approval, automated, multi_device, test), message, member { id, name } or null, createdAt
- member.joined
- Someone joined. An invitation was accepted.
- data: member { id, name, email }, role, departmentId
- time_entry.stopped
- A timer stopped. Time booked to a project with the timer.
- data: id, member, project, task, startedAt, endedAt, durationSec, note
- time_entry.created
- Time added by hand. An entry added to a project afterwards.
- data: id, member, project, task, startedAt, endedAt, durationSec, note
- leave.created
- Leave recorded. Leave or a holiday was added or requested.
- data: id, member (null for a company holiday), type, part, minutes, status, startDate, endDate
- leave.updated
- Leave decided. A leave request was approved or rejected.
- data: id, member, type, part, minutes, status, startDate, endDate
- ping
- A test. The “Send test” button in Settings.
- data: message
What arrives
POST https://your-endpoint.example.com/timerfly
Content-Type: application/json
Timerfly-Event: leave.updated
Timerfly-Delivery: 3f6c…
Timerfly-Signature: t=1790661600,v1=5d41402abc4b2a76b9719d911017c592…
{
"id": "3f6c…",
"event": "leave.updated",
"createdAt": "2026-09-28T09:20:00.000Z",
"organization": { "id": "ada9…" },
"data": {
"id": "91b2…",
"member": { "id": "7554…", "name": "Aditya Kulkarni" },
"type": "vacation",
"part": "full",
"minutes": null,
"status": "approved",
"startDate": "2026-10-06",
"endDate": "2026-10-08"
}
}- Answer with any 2xx within 10 seconds. Do slow work afterwards.
- Retries: if your endpoint is down or answers anything else, Timerfly tries again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. Redirects aren’t followed.
- Idempotency: a retry has the same
id(also in theTimerfly-Deliveryheader). Skip ids you’ve already handled. - Health: each webhook’s log in Settings shows its latest deliveries and their results. After 50 failures in a row it’s switched off and your owners and admins get an email.
- Addresses: public https only, never private or internal network addresses.
Checking the signature
Timerfly-Signature is t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of t + "." + the raw body with the webhook’s signing secret (whsec_…, under Secret in Settings). Compare in constant time and reject old timestamps.
Node.js
import crypto from 'node:crypto';
// req.rawBody: the request body exactly as received (before JSON.parse).
function isFromTimerfly(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // older than 5 minutes: replay
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}Python
import hmac, hashlib, time
def is_from_timerfly(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])PHP
function is_from_timerfly(string $rawBody, string $header, string $secret): bool {
parse_str(str_replace(',', '&', $header), $p);
if (abs(time() - (int) $p['t']) > 300) return false;
$expected = hash_hmac('sha256', $p['t'] . '.' . $rawBody, $secret);
return hash_equals($expected, $p['v1']);
}
// $raw = file_get_contents('php://input'); $sig = $_SERVER['HTTP_TIMERFLY_SIGNATURE'];Zapier, Make and n8n
No code needed: point a webhook at their “catch hook” address and use the fields in any of their apps. To read reports from them, call the API with an HTTP / Webhooks GET step and the Authorization header.
In the help centre: Does Timerfly work with Zapier, Make or Google Sheets?
Errors & limits
- 400
- A parameter is missing or wrong (for example a date that isn’t YYYY-MM-DD, `to` before `from`, or more than 92 days).
- 401 invalid_api_key
- No key, a mistyped key, or a revoked one.
- 403 plan_required
- The company’s plan doesn’t include the API (it’s on Business).
- 403 workspace_paused
- The trial or plan ended and wasn’t renewed. Nothing is deleted; it answers again once a plan is chosen.
- 429 rate_limited
- More than 120 requests in a minute with one key. The count starts again each minute, so wait for the next one and try again.
Errors are JSON: { "statusCode": 400, "message": "…" }, with a code where there’s one to act on.
Versions
v1, 28 September 2026. New fields and events may be added to v1; anything that would break existing code gets a new version.
Questions
Does Timerfly have an API?
Yes. Timerfly has a read-only REST API (v1) that returns JSON: people, departments, attendance per day, hours, apps and websites, projects, time entries, leave and who’s working now. It’s on the Business plan and in the 14-day free trial.
Is the API on every plan?
No. The API and webhooks are on the Business plan. Every 14-day free trial includes them, so you can test with your own team’s data first. On Starter or Pro the API answers 403 plan_required and webhooks stop sending.
Does Timerfly work with Zapier?
Yes, and with Make and n8n. Create a “catch hook” in the automation tool, paste its address into Settings → API & integrations → Webhooks, and Timerfly sends each event as it happens. To read reports from them, call the API from an HTTP step with your key.
Can Timerfly send webhooks to our HR system?
Yes. Add any public https address and choose from 7 events: someone started work, an alert fired, someone joined, a timer stopped, time was added by hand, leave was recorded and leave was decided. Each request is signed with HMAC-SHA256 so your system can check it came from Timerfly.
Can the API change data in Timerfly?
No. Every endpoint is a GET. A key reads its own company’s data and can’t add, edit or delete anything. An owner or admin can revoke a key at any time and it stops working at once.
How does the API sign in, and is there a rate limit?
With an API key in the Authorization header (Bearer tf_…). Keys are shown once and stored only as a hash. Each key may make 120 requests a minute, and one request can cover up to 92 days.
Are screenshots available through the API?
No. The API returns attendance, time, apps, projects and leave. Screenshots stay inside Timerfly.