Partner API Overview #
The Friday API is a REST API that lets you integrate with the Friday HR and payroll platform. You can read company data, manage employees, track time, process payroll, and stay in sync through real-time webhooks — all from your own application.
Base URL #
All API endpoints are served under a single base path. During the onboarding and integration phase, use the sandbox environment:
https://node.friday-staging.com/partner/v1
Every endpoint referenced in this guide and the rest of the documentation is relative to this base URL. For example, GET /employees means:
GET https://node.friday-staging.com/partner/v1/employees
When you are ready to go live, use the production base URL:
https://api.fridayapp.com/partner/v1
API access is self-serve. Friday does not manually approve your integration before you can use the live endpoint.
Authentication #
The API uses API key authentication. Pass your key in the X-API-Key header on every request:
curl -X GET https://node.friday-staging.com/partner/v1/companies
-H “X-API-Key: fri_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2”
Each API key is scoped to a single company. All data you read or write through that key is automatically scoped to that company — you never need to specify a company ID in the URL.
If you need to integrate with multiple Friday companies, generate a separate key for each one.
API keys are created and managed in the Developer Portal. See the Getting API Access guide for the full setup walkthrough.
Coming soon — OAuth 2.0 with multi-app support is on the roadmap. This will let a single application request access to multiple Friday companies through a standard authorization flow.
Plans and Access #
The endpoints available to your API key depend on the company’s plan. There are three plan tiers, each building on the one below it:
| Plan | What it unlocks |
|——|—————-|
| Timetracking | Companies, Employees, Customers and projects, Time Records, Timetrack reports, PTO, Departments |
| Payroll | Everything above + Payrolls, Payroll Reports, Pay Schedule Groups, Workplaces |
| Premium | Everything above + premium features |
If you call an endpoint that requires a higher plan than the company has, the API returns 403:
{
“error”: “Your plan does not include access to this resource. Please upgrade to the payroll plan.”
}
Available Resources #
Here’s a summary of every resource the API exposes, grouped by plan tier.
Timetracking plan #
| Resource | Description | Key endpoints |
|———-|————-|—————|
| Companies | The company linked to your API key — name, address, plan, and settings. | GET /companies |
| Employees | Employee records including contact info, department, pay type, and status. Filter by active status, department, or search by name. | GET /employees, GET /employees/:id, PATCH /employees/:id, POST /employees/invite |
| Customers and projects | Customers (jobs or job sites) and projects nested under them for granular time tracking. Use customer and project IDs on clock-in, filters, and reports. | GET /customers, GET /customers/:id, PATCH /customers/:id, GET /projects, GET /projects/:id, PATCH /projects/:id |
| Time Records | Individual clock-in/clock-out entries. Create time entries programmatically or query historical records with filters for employee, date range, and type. | GET /time-records, GET /time-records/:id, POST /time-records/clock-in, POST /time-records/clock-out |
| Timetrack Reports | Aggregated time tracking reports at the company or employee level, with daily breakdowns and optional customer/project grouping. Downloadable as PDF or CSV. | GET /timetrack/company, GET /timetrack/company/download, GET /timetrack/employee/:id |
| PTO | PTO balances and time-off requests. View balances per employee, submit new requests, and approve or deny pending ones. | GET /pto/balances, GET /pto/balances/:id, GET /pto/requests, POST /pto/requests, POST /pto/requests/:id/approve, POST /pto/requests/:id/deny |
| Departments | Organizational groupings for employees. Create, update, and delete departments. | GET /departments, GET /departments/:id, POST /departments, PATCH /departments/:id, DELETE /departments/:id |
Payroll plan (adds) #
| Resource | Description | Key endpoints |
|———-|————-|—————|
| Payrolls | Full payroll lifecycle — discover available pay periods, initialize employee earnings, create a draft with cost preview, and approve for processing. Also retrieve past payrolls, download pay stubs, and access check data. | GET /payrolls/period-options, POST /payrolls/initialize, POST /payrolls, GET /payrolls, GET /payrolls/:id, and more |
| Payroll Reports | Seven report types covering payroll summaries, cash requirements, tax liability, tax deposits, W-4 status, W-2 previews, and contractor payment summaries. | GET /payroll-reports/company-payroll-summary, GET /payroll-reports/cash-requirement, and more |
| Pay Schedule Groups | The company’s pay schedules (weekly, biweekly, semimonthly, monthly) and which employees are assigned to each. | GET /pay-schedule-groups, GET /pay-schedule-groups/:id |
| Workplaces | Physical business locations used for payroll tax purposes. | GET /workplaces, GET /workplaces/:id |
Pagination #
List endpoints return paginated results. Control pagination with two query parameters:
| Parameter | Default | Range | Description |
|———–|———|——-|————-|
| page | 1 | 1+ | The page number to retrieve |
| per_page | 25 | 1–100 | Number of records per page |
Every paginated response includes a pagination object:
{
“data”: [ … ],
“pagination”: {
“page”: 1,
“per_page”: 25,
“total_count”: 142,
“total_pages”: 6
}
}
Use total_pages to know when to stop paginating. If you request a page beyond the last page, the API returns an empty data array.
Error Handling #
The API uses standard HTTP status codes and returns errors in a consistent format:
{
“error”: “A human-readable description of what went wrong”
}
Common status codes #
| Code | Meaning |
|——|———|
| 200 | Success |
| 201 | Created (returned by POST endpoints that create a resource) |
| 400 | Bad request — invalid parameters or request body |
| 401 | Unauthorized — missing or invalid API key |
| 403 | Forbidden — the company’s plan doesn’t include this resource |
| 404 | Not found — the requested resource doesn’t exist |
| 429 | Rate limit exceeded — back off and retry |
| 500 | Server error — something went wrong on our end |
Rate Limiting #
The API enforces a rate limit of 100 requests per 60 seconds per API key, using a sliding window.
When you exceed the limit, the API returns 429 Too Many Requests. Wait for the window to reset before retrying. If you need to make many requests in a short time (e.g., syncing a large dataset), spread them out or paginate with larger per_page values.
Webhooks #
Instead of polling for changes, you can register webhook endpoints to receive real-time push notifications when data changes in Friday. The API emits events across 10 resource types — employees, time records, PTO requests, payrolls, customers and projects (as separate event families), departments, pay schedule groups, workplaces, and the company itself.
Each webhook delivery includes an HMAC-SHA256 signature for verification, a unique event ID for deduplication, and the full resource object matching the corresponding API response shape.
See the Subscribing to Webhooks guide for setup instructions, payload format, signature verification, and the full event catalog.
Request Logs #
The Developer Portal includes a built-in request log viewer for each API key. Every request is logged with the HTTP method, path, status code, and timestamp. You can filter by method, path, status code, and date range — useful for debugging integration issues without digging through your own logs.
Quick Start #
If you’re new to the Friday API, here’s the recommended path:
- Get access — Follow the Getting API Access guide to enable API access, generate an API key, and make your first request.
- Test the integration — Follow the Testing the Integration guide to use the API Reference and Postman collection against sandbox.
- Track time — If your integration uses time tracking, read the Timetracking guide.
- Track job costs — If you need labor totals by customer or project, read the Job Costing guide.
- Set up webhooks — Stay in sync with real-time events by following the Subscribing to Webhooks guide.
- Process payroll — If the company is on a payroll plan, walk through the full payroll lifecycle in the Payroll Processing guide.
- Use the MCP server — If you use AI coding tools, connect them to Friday API context with the MCP Server guide.
Other Guides #
| Guide | What it covers |
|——-|—————|
| Getting API Access | Self-serve API access, Developer Portal login, environment selection, and API key generation |
| Testing the Integration | API Reference, Postman collection, sandbox testing flow, and error cases |
| Customers and projects | How customers and projects relate, listing and updates, and links to time tracking and webhooks |
| Timetracking | Time records, clock-in/out, breaks, switches, geofencing, and reports |
| Job Costing | Track labor time by customer/project and report totals by job |
| The Employee Object | Employee fields, employment types, timetrack-only, manager types, earnings, multiple records per person |
| Inviting an Employee | The invite endpoint: required fields per employment type and plan, wage branching, examples |
| The Payroll Life Cycle | Payroll statuses, state transitions, and how to track them via API and webhooks |
| Processing Payroll | End-to-end payroll: period discovery, draft creation, cost preview, approval |
| Subscribing to Webhooks | Endpoint registration, signature verification, event types, retries |
| MCP Server | Connect AI coding tools to Friday API documentation context |
