API Overview
The BookYourPTO REST API lets your own scripts, internal systems and integration tools (iPaaS platforms such as Zapier, Make or Workato) read and work with your organization's data. It is a second way into the same data you see in the app, held to the same rules: anything a token can see or do, the person who owns it could already see or do in BookYourPTO.
Base URL
Every endpoint lives under one base URL:
https://app.bookyourpto.com/api/v1
If your organization uses a custom domain, GET /organization returns the base URL to use in its base_url field.
All requests and responses use JSON over HTTPS. The API is designed for server-to-server use: it sends no CORS headers, so a web page on another site cannot call it from a browser. Call it from your own back end, a scheduled job or an integration platform.
Who can use the API
| Requirement | Detail |
|---|---|
| Plan | API access is included in every paid plan: Pro, Business and Enterprise. It is not available on the Free plan. |
| Organization switch | The API is off by default. An Executive switches it on under Settings > API > Settings. While it is off, every token is refused and no new tokens can be created. |
| Who may create tokens | By default Administrators and Executives. An Executive can allow other roles to create personal tokens for themselves. |
| Subscription in good standing | A subscription that is past due, suspended, cancelled or unpaid stops every token until it is resolved. |
These conditions are checked again on every request, not only when a token is created. Downgrading to Free, switching the API off, or a lapsed subscription stops all tokens at once.
A token acts as its owner
Every API token is owned by one person in your organization. On each request the token acts as that person:
- Visibility is the owner's. A department head's token sees what that department head sees in the app; an employee's token sees what that employee sees. Privacy settings, private leave types and department restrictions apply exactly as they do in the app.
- Scopes narrow it further. A token only reaches the areas its scopes allow. A scope never widens what the owner could do.
- The owner's role sets a ceiling. Each scope has a minimum role. A token cannot hold a scope above its owner's role, and if the owner is later demoted, scopes above the new role stop working on the next request.
- The owner's account must stay in good standing. If the owner is deactivated or offboarded, or is no longer in a role allowed to hold tokens, the token stops working immediately. Offboarding revokes the owner's tokens permanently. See Authentication & Tokens.
- Writes follow the app's rules. A request made through the API goes through the same business rules as the same action in the app: notice periods, balances, locked dates, approval chains, notifications and calendar sync. Every write is recorded in the organization's audit log with the token that made it.
What you can do with it
| Area | Read | Write |
|---|---|---|
| People | The directory, employment details, departments, teams, training, certifications, equipment, benefits, compensation, custom fields, goals and onboarding checklists | Add and update people, departments and teams; assign training; issue and update equipment |
| Leave | Leave types, requests, balances, public holidays and locked dates | Request and cancel leave; approve and reject requests and cancellation requests |
| Time | Time entries, timesheets, projects, tasks, clients and shifts | Create, edit and delete time entries; approve and reject them |
| Expenses & Documents | Expense reports with their line items, and document metadata, signers and files | Approve and reject expense reports |
| Webhooks | Endpoints, delivery logs and the event catalogue | Subscribe to events, test and redeliver |
Some things are deliberately not available through the API: clocking in and out (location and geofence checks belong to the device), signing documents (a signature is a legal act bound to a person), billing, single sign-on, custom domains and imports.
What is in this section
| Page | What it covers |
|---|---|
| Getting Started | Switch the API on, create a token and make a first request |
| Authentication & Tokens | Token format, expiry, rotation, revocation and IP allowlists |
| API Roles & Scopes | Reusable API roles, the built-in templates and the scope catalogue |
| Requests & Responses | The response envelope, field naming, dates, pagination and idempotency |
| Errors | Every error code and what to do about it |
| Rate Limits | The limits, the headers that report them and how to back off |
| Guides | Common tasks for people, leave, time, expenses and documents, with visibility rules and gotchas |
| Webhooks | Receiving events instead of polling |
| Postman & OpenAPI | Downloading the specification and the Postman collection |
| Versioning & Changes | What can change within the API and how breaking changes are handled |
| API Reference | Every endpoint, its parameters and its response schema |
The API Reference is generated from the API itself, so it always lists exactly the endpoints that are available. The guides in this section describe the rules every endpoint shares and walk through common tasks.