Connect BookYourPTO to Your Own Systems: A Public REST API and Signed Webhooks

Why an API, and why now

Most teams that run leave, time and expenses in BookYourPTO also run something else: a payroll provider, an HRIS, a finance system, a dashboard somebody built in a spreadsheet. Until now, the only way to move data between them was an export, a download and an upload — repeated every pay period, by hand.

BookYourPTO now has a public REST API and outbound webhooks. Your own scripts and tools can read and write your HR data directly, and your systems can be told the moment something changes instead of asking every few minutes. Both are included on the Pro, Business and Enterprise plans. They are off until an executive in your organization switches them on.

What you can build with it

A few of the jobs the API is shaped for:

• HRIS and directory sync. Read people, departments and teams, and create or update people from the system that owns your employee records.
• Payroll export. Pull approved time entries, finalized timesheets, leave and leave balances for a pay period, in plain JSON, instead of assembling a spreadsheet.
• Leave dashboards. Feed who is away, for which leave type, into a wall display, an intranet page or a BI tool — with public holidays and locked dates alongside.
• Approvals from where people already work. Approve or reject leave requests, time entries and expense reports from your own tooling, under the same rules as the app.
• Event-driven automations. Integration platforms such as Zapier, Make and Workato can receive webhooks and call REST APIs through their webhook and HTTP steps, so a leave approval, a new starter or a paid expense report can start a workflow elsewhere.

The API covers people, departments, teams, leave types, leave requests and balances, holidays, time entries, timesheets, projects and clients, schedules, expense reports, document records, onboarding, and per-person records such as training, certifications, assets and goals. A few things are deliberately left out: signing a document is a legal act tied to a person, and clocking in depends on the device's location, so neither is available through the API.

Webhooks: be told, rather than ask

Polling an API every few minutes is wasteful and still late. A webhook endpoint receives an HTTPS request when something happens. Events cover the life of a leave request (requested, approved, rejected, updated, cancellation requested, cancelled), people (added, updated, deactivated, reactivated), departments, time entries and finalized timesheets, expense reports through to paid, and signed or declined documents.

Each delivery carries a unique event id that stays the same across retries, so your receiver can ignore a duplicate. A receiver that is down or returns an error is retried on a schedule that backs off over roughly two days, and every attempt is visible in a delivery log, where a failed delivery can be sent again. A Send test event button lets you check a new endpoint before relying on it.

The security model, in plain words

An API is a second door into the same data, so it has to be held to the same rules as the first. These are the ones that matter:

• A token acts as a person. Every token belongs to someone in your organization and sees exactly what that person could see in the app — computed by the same permission checks the app uses, not a copy of them. An employee's token sees what that employee sees. A department head's token stays within their department.
• It follows that person. If its owner is deactivated, offboarded, or moved to a role that may not hold tokens, the token stops working on the very next request.
• Scopes limit it further. A token is created with only the permissions it needs — read the directory, read leave, approve time entries — and can never hold a scope above its owner's role. The most sensitive fields, such as personal details and compensation, need their own scopes and are recorded every time they are read.
• Every token expires. There is no "never". Your organization sets the longest lifetime allowed, and the owner is emailed a week before a token runs out. A token can be rotated with a short overlap so an integration does not drop, and revoked at any time.
• IP allowlists. A token can be restricted to the addresses or ranges your servers actually call from.
• Rate limits. Each token and each organization has a request budget per minute, and every response says how much is left, so one runaway script cannot affect anyone else.
• Signed webhooks. Every delivery is signed using the open Standard Webhooks scheme, so your receiver can prove it came from us and has not been replayed. Endpoints must use HTTPS, the signing secret is shown once and stored encrypted, and payloads contain only what the endpoint's owner is allowed to read.
• Everything is on the record. Every change made through the API is written to the audit log, marked as made through the API and naming the token that made it.

Getting started

An executive switches the API on under Settings → API, where your organization also chooses who may create tokens and how long a token may last. From there you create a token — from a ready-made template such as Leave sync or Read-only directory, or with exactly the scopes you choose — and add webhook endpoints.

The full reference, with every endpoint, a downloadable OpenAPI description and a Postman collection, is in the app, and the guides are in our documentation: API overview.