Skip to content
Timerfly

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

  1. 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.
  2. Send it on every request: Authorization: Bearer tf_…
  3. Base address: https://api.timerfly.com/api/v1
  4. Call /me to 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=deactivatedAlso people who were deactivated.

GET /departments

Departments: id and name.

GET /days

Attendance and time, one row per person per day.

fromFirst day, YYYY-MM-DD (required).
toLast day (default: from). Up to 92 days.
memberIdOne 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.

fromRequired.
toOptional.
memberIdOne 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.

fromRequired.
toOptional.
memberIdOne person.
projectIdOne 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.

fromRequired.
toOptional.
memberIdOne 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 the Timerfly-Delivery header). 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.

Try the API on your own team’s data
The API and webhooks are in the 14-day free trial, no card needed.
Start free trial