Once you’ve decided to offer payroll within your application, the next question is: build, buy, or embed? Buying is costly and requires system integration work. Building is time-consuming, and may take years – plus, you’ll need to stay up-to-date with ever-changing tax and compliance laws. Embedding payroll offers a happy middle ground: a native frontend that lives within your application, with the operational complexities of payroll abstracted away and handled by a partner like Gusto via an application programming interface (API).
APIs let you offer payroll seamlessly within your platform, driving deeper user engagement and opening new revenue opportunities. API-driven payroll solutions like Gusto Embedded abstract away regulatory complexities, while providing a developer-friendly infrastructure, so that you can focus on providing employers on your platform with the unique benefits of offering payroll (and payroll data) within your platform.
In this guide, you’ll learn how payroll APIs enable secure, programmatic access to employee data, what types of data they expose, and which common operations you can use to integrate payroll functionality into your applications.
Integrate Payroll APIs to Streamline Operations
Integrating payroll APIs with internal business applications has several benefits. Here’s why businesses and software-as-a-service (SaaS) developers should integrate payroll APIs with their systems:
| Efficiency | Payroll APIs help businesses streamline data handling across the organization and reduce payroll processing time. Teams can use APIs to create custom workflows, automating repetitive tasks like time off tracking, payroll processing, tax calculations, payslip generation, and report generation. |
| Data accuracy | Payroll APIs reduce the possibility of human errors in payroll data entry, enabling accurate payroll calculations and tax filings. For example, businesses can use the data from the APIs to calculate applicable federal and state tax withholdings for full-time employees or automate wage calculations for hourly workers. |
| Compliance | Payroll APIs reduce the amount of manual work needed to maintain regulatory compliance. |
| Scalability | Payroll APIs easily scale with the organization, reducing the manual overhead for HR, finance, and accounting teams. For example, when new employees are hired or existing employees leave the organization, employee records need to be kept in sync with multiple internal systems to ensure data accuracy. Payroll APIs make it easy to quickly onboard or offboard employees and automatically sync the data across different systems. |
Payroll data can be integrated into a centralized dashboard with financial and operational data to provide insights into costs, operations, and business efficiency. Employee expenses often contribute to a business’s most significant costs; integrating payroll data with other expenses and revenue data can help companies better understand their finances and optimize resource and budget allocation.
Access Payroll Data Through APIs
Gusto Embedded provides comprehensive APIs to access all kinds of employee data, including compensation data, time and attendance data, and payroll processing data.
Employee Data
Employee APIs help access and manage employee data, including full name, date of birth, contact details, employment status, and job title. For instance, the /v1/employees/{employee_id} endpoint can be used to retrieve an employee’s details.
The following code snippet shows a request to get an employee’s data:
curl --request GET \
--url https://api.gusto-demo.com/v1/employees/123 \
--header 'X-Gusto-API-Version: 2024-04-01' \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_TOKEN'
The API returns a response containing employee data like this:
{
"uuid": "d59f0776-107e-4c43-a148-564a14c8cdbf",
"first_name": "Kurtis",
"last_name": "McKenzie",
"company_uuid": "cc82c11f-d4ba-4f55-aace-2fb7b1fefa1f",
"onboarding_status": "onboarding_completed",
...
"jobs": [
{
...
"title": "Engineer",
"hire_date": "2025-05-16",
"location": {
"uuid": "3ee20a56-8931-47f4-94c7-e637dda8cf74",
...
"zip": "94107",
"country": "USA",
"inactive": false
}
}
],
...
"date_of_birth": "2005-05-16"
}
Compensation Data
Compensation APIs help manage salary and wage details for employees. For instance, the /v1/compensations/{compensation_id} endpoint can be used to fetch information about how much an employee is paid for a job.
The following code snippet shows a request to get compensation details using the compensation_id:
curl --request GET \
--url https://api.gusto-demo.com/v1/compensations/x123 \
--header 'X-Gusto-API-Version: 2024-04-01' \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_TOKEN'
The API returns a response containing wage data like this:
{
"uuid": "db57832c-d8bc-43a7-ae99-0a04480ff037",
"version": "98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872",
"job_uuid": "d8f8fbe7-496d-4b69-86f0-1e2d1b73a086",
"rate": "60000.00",
"payment_unit": "Year",
"flsa_status": "Exempt",
"effective_date": "2025-05-11",
"adjust_for_minimum_wage": false,
"minimum_wages": []
}
Similarly, you can use the POST /v1/jobs/{job_id}/compensations endpoint to create compensation for a job.
Time and Attendance Data
Time-off APIs help companies track work hours and time off, including hours worked per pay period, paid time off (PTO), sick leave balances, and time-off requests. For instance, the /v1/employees/{employee_uuid}/time_off_activities endpoint returns the time-off details for an employee.
The following code snippet shows a request to get the time-off activities for an employee using the employee_id:
curl --request GET \
--url https://api.gusto-demo.com/v1/employees/123/time_off_activities \
--header 'X-Gusto-API-Version: 2024-04-01' \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_TOKEN'
The API returns a response containing employee time-off activities:
[
{
"policy_uuid": "a7838f74-4c29-4b70-9bfb-02a4e3e60709",
"time_off_type": "vacation",
"policy_name": "Paid Time Off",
"event_type": "TimeOffEvent::AddToPolicy",
"event_description": "Added to policy: Vacation Per Hour Worked",
"effective_time": "2025-05-27T13:43:03.000-07:00",
"balance": "0.0",
"balance_change": "0.0"
},
...
]
Gusto also provides API endpoints to granularly manage and view time-off policies.
Tax and Compliance Data
Tax and compliance APIs help businesses handle tax-related information, including federal and state tax withholdings, deductions, garnishments, and tax-filing status for their employees. The /v1/employees/{employee_uuid}/federal_taxes endpoint returns the attributes relevant to an employee’s federal taxes.
The following code snippet shows a request to get the federal tax attributes for an employee using the employee_id:
curl --request GET \
--url https://api.gusto-demo.com/v1/employees/123/federal_taxes \
--header 'X-Gusto-API-Version: 2024-04-01' \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_TOKEN'
The API returns a response containing the employee’s federal tax attributes:
{
"version": "56a489ce86ed6c1b0f0cecc4050a0b01",
"filing_status": "Single",
"extra_withholding": "0.0",
"two_jobs": true,
"dependents_amount": "0.0",
"other_income": "0.0",
"deductions": "0.0",
"employee_id": 29,
"w4_data_type": "rev_2025_w4"
}
Similarly, the /v1/employees/{employee_uuid}/state_taxes endpoint can be used to fetch attributes related to the employee’s state taxes. Additionally, Gusto provides APIs to store and retrieve employee I-9 authorization details needed by US federal law for employment eligibility verification.
Payroll Processing Data
Payroll processing APIs help companies manage payroll cycles and payments. These APIs can be used to submit a payroll run, calculate taxes for unprocessed payrolls, and access pay statements. The /v1/payrolls/{payroll_uuid}/receipt endpoint returns a payroll receipt with compensation and tax information.
The following code snippet shows a request to get the payroll receipt using the payroll_uuid:
curl --request GET \
--url https://api.gusto-demo.com/v1/payrolls/payroll_uuid/receipt \
--header 'X-Gusto-API-Version: 2024-04-01' \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_TOKEN'
The API returns a response containing the tax and compensation details for the specified payroll UUID:
{
"totals": {
"company_debit": "1080.47",
...
},
"taxes": [
{
"name": "Federal Income Tax",
"amount": "30.36"
},
...
],
"employee_compensations": [
{
"employee_uuid": "f83d0bd8-7e20-43b9-834c-6d514ef6cb47",
"employee_first_name": "Patricia",
"employee_last_name": "Hamill",
"payment_method": "Direct Deposit",
"net_pay": "748.34",
"total_tax": "182.13",
...
}
],
"licensee": {
"name": "Gusto, Zenpayroll Inc.",
"address": "525 20th St",
...
},
"payroll_uuid": "afccb970-357e-4013-81f5-85dafc74f9b6",
"company_uuid": "c827aa0d-3928-4d5a-ab1f-400641a7d2b8",
"name_of_sender": "Torp and Sons and Sons",
"name_of_recipient": "Payroll Recipients",
...
}
Gusto provides a comprehensive set of API endpoints to manage and view payroll data and offers APIs that integrate with external payrolls.
How One Partner Uses the Gusto Embedded Payroll API for a Seamless User Experience
Vagaro is a salon, spa, and fitness management platform that integrates Gusto for payroll. Their early integration allowed Vagaro customers (business owners) to link their accounts and run payroll using Gusto. This integration made it easier for business owners to run payroll, but it still required managing two separate accounts, which made keeping data in sync challenging.
Recently, Vagaro integrated the Gusto Embedded Payroll API to offer fully integrated payroll services within its application and cut its customers’ time on payroll in half. With the embedded integration, business owners don’t need to open a Gusto account. They can easily run payroll, request time off, view employees’ time-off balances, and do more, all within the Vagaro application.
To learn more about how Vagaro uses Gusto Embedded, check out this interview with Fred Helou and watch a recording of the webinar that features Vagaro customer Cassidee, owner of Golden State Strands Salon.
Use Core API Operations for Payroll Management
To seamlessly integrate payroll APIs with their systems, developers need to perform multiple API operations, including authentication. This section discusses the most common API operations for integrating a payroll system, covering how to:
- Manage authentication and security
- Retrieve employee data
- Create and update payroll records
- Address tax calculations and compliance reporting
- Handle webhooks for real-time updates
Manage Authentication and Security
Before calling any payroll API, you need to obtain a company access token, as illustrated in this diagram:
The Gusto Getting Started guide describes the authentication process in detail, but here are the broad steps you need to follow:
- Create a new application using the Gusto developer portal to obtain a
client_idandclient_secret. - Call the
/oauth/tokenendpoint using the client ID and secret to obtain a systemaccess_token, which is valid for two hours. - If you haven’t already created a company, call the POST
/v1/partner_managed_companiesendpoint using the systemaccess_tokento create a new company. For example, here’s the code snippet to create a company:
curl --request POST \
--url https://api.gusto-demo.com/v1/partner_managed_companies \
--header 'X-Gusto-API-Version: 2024-04-01' \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
--header 'content-type: application/json'
The API returns the company UUID, access token, and refresh token, as shown here:
{
"access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",
"refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1",
"company_uuid": "d525dd21-ba6e-482c-be15-c2c7237f1364",
"expires_in": 7200
}
You need to pass this access_token with every payroll API request. Notice that the access expires in two hours. You can exchange the refresh_token for a new access token using the OAuth token API. The previous refresh_token will be revoked on the first usage of the new access_token.
Retrieve Employee Data
Payroll APIs let you fetch detailed employee information, including personal data, payroll status, and compensation history:
- Use the GET
/v1/employees/{employee_id}endpoint to fetch employee details based on anemployee_id. In addition to personal details, this API also returns a list ofjobsassociated with the employee. - Use the GET
/v1/employees/{employee_id}/pay_stubsendpoint to fetch an employee’s pay stub history. - Fetch compensation history for a specific job using the
GET/v1/jobs/{job_id}/compensationsendpoint, which contains information on how much is paid out for a job. For example, the following code snippet shows a request that returns the compensation for the specifiedjob_id:
curl --request GET \
--url https://api.gusto-demo.com/v1/jobs/123/compensations \
--header 'X-Gusto-API-Version: 2024-04-01' \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_TOKEN'
By default, the API returns only the current compensation:
[
{
"id": 1363316536327003,
"job_id": 1123581321345589,
...
"payment_unit": "Hour",
"flsa_status": "Nonexempt",
"effective_date": "2018-12-11",
"rate": "5.00",
"adjust_for_minimum_wage": true,
"minimum_wages": [
{
"uuid": "edeea5af-ecd6-4b1c-b5de-5cff2d302738",
"wage": "7.25",
"effective_date": "2025-05-11"
}
]
}
...
]
Create and Update Payroll Records
A critical part of managing HR operations is calculating gross pay, applying tax deductions, and ensuring that employees receive accurate salaries on time. While much of this is handled by Gusto Embedded, you need to ensure the inputs are accurate. Payroll APIs support creating and updating employee payroll records, including wages and other compensation details.
The POST /v1/companies/{company_id}/payrolls endpoint can be used to create a new unprocessed payroll. For example, the following code snippet shows a curl request that creates an off-cycle payroll for the specified company_id:
curl --request POST \
--url https://api.gusto-demo.com/v1/companies/{company_id}/payrolls \
--header 'X-Gusto-API-Version: 2024-04-01' \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_TOKEN' \
--header 'content-type: application/json' \
--data '{"off_cycle": true, "off_cycle_reason": "Bonus"}'
The API returns the details of the newly created payroll:
{
"version": "19289df18e6e20f797de4a585ea5a91535c7ddf7",
"payroll_deadline": "2022-02-18T22:00:00Z",
"check_date": "2025-02-22",
"off_cycle": true,
...
"uuid": "b50e611d-8f3d-4f24-b001-46675f7b5777",
"payroll_uuid": "b50e611d-8f3d-4f24-b001-46675f7b5777",
"company_uuid": "6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb",
"created_at": "2025-02-01T22:00:00Z",
"pay_period": {
"start_date": "2025-02-01",
"end_date": "2025-02-15",
"pay_schedule_uuid": "00ebc4a4-ec88-4435-8f45-c505bb63e501"
},
...
}
Additionally, an existing payroll can be updated using the PUT /v1/companies/{company_id}/payrolls/{payroll_id} endpoint. For example, the following code snippet shows a request that updates a payroll for the specified company_id and payroll_id:
curl --request PUT \
--url https://api.gusto-demo.com/v1/companies/{company_id}/payrolls/{payroll_id} \
--header 'X-Gusto-API-Version: 2024-04-01' \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_TOKEN' \
--header 'content-type: application/json' \
--data '{"withholding_pay_period": "Twice per month", "fixed_withholding_rate": true}'
The API returns the details of the updated payroll:
{
"payroll_deadline": "2022-02-18T22:00:00Z",
"uuid": "b50e611d-8f3d-4f24-b001-46675f7b5777",
"payroll_uuid": "b50e611d-8f3d-4f24-b001-46675f7b5777",
"company_uuid": "6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb",
"created_at": "2022-02-01T22:00:00Z",
"pay_period": {
"start_date": "2025-02-01",
"end_date": "2025-02-15",
"pay_schedule_uuid": "00ebc4a4-ec88-4435-8f45-c505bb63e501"
},
...
}
Address Tax Calculations and Compliance Reporting
Based on each employee’s status, companies need to apply the correct withholding and deductions before processing a payroll. This ensures that the employees receive accurate salaries and that adequate taxes are withheld based on their residence status. The PUT /v1/companies/{company_id}/payrolls/{payroll_id}/calculate endpoint can be used to perform calculations for taxes, benefits, and deductions for an unprocessed payroll.
Additionally, Gusto provides APIs to store and retrieve I-9 documents, as well as signatures and other information required to complete the I-9 form for employment eligibility verification.
The PUT /v1/employees/{employee_id}/i9_authorization endpoint stores information about an employee’s authorization status.
The GET /v1/employees/{employee_id}/i9_authorization endpoint lets organizations fetch the status and details of an employee’s work authorization. For example, the following request can be used to fetch the details for an employee:
curl --request GET \
--url https://api.gusto-demo.com/v1/employees/123/i9_authorization \
--header 'X-Gusto-API-Version: 2024-04-01' \
--header 'accept: application/json' \
--header 'authorization: Bearer YOUR_TOKEN'
The API returns only the I-9 authorization details:
[
{
"version": "6ae7ff720107b356bf13b1606f60b24f",
"uuid": "7f2337f9-9b78-44b9-aeed-be4777b833a8",
"form_uuid": "c54046f7-1be4-4c54-8194-f4842c30c86d",
"authorization_status": "alien",
"document_type": "foreign_passport",
"has_document_number": true,
"expiration_date": "2027-01-01",
"country": "Panama",
"employer_signed": false,
"employee_signed": false,
"additional_info": "Notes",
"alt_procedure": false
}
]
Handle Webhooks for Real-Time Updates
A webhook is an HTTP request that allows an application to automatically notify another application when a specific event occurs. Gusto supports a comprehensive set of webhook events, allowing you to receive real-time notifications when key payroll events occur, such as new hires, terminations, or pay runs.
Employee events notify you of different events, such as created, updated, onboarded, and terminated. These webhooks can be used to automate employee onboarding and offboarding data syncs across internal systems.
For example, when an employee is added to the company’s payroll, a webhook employee.created event will be triggered:
{
"uuid": "03ffbf0c-48a9-4f1c-932a-546413a26ad1",
"event_type": "employee.created",
"resource_type": "Company",
"resource_uuid": "5df911a0-e8e9-412d-8aaf-a46ad193dd96",
"entity_type": "Employee",
"entity_uuid": "bcfc9744-0ab3-4ef3-ab0d-e728255d659c",
"timestamp": 1671058841
}
Other internal systems can subscribe to these events to sync employee records, grant tooling access, and create accounts. You can configure webhooks using the Gusto developer portal.
Build Custom Solutions with Payroll APIs
Developer-friendly and comprehensive Gusto Payroll APIs can be used to build custom solutions, including the following:
| Payroll dashboards | Developers can integrate payroll insights directly into SaaS platforms, providing real-time visibility into employee costs, revenue, and other expenses. For example, with the General Ledger report API, you can retrieve structured, granular JSON payroll reports, aggregated by different dimensions such as job or department. |
| Time tracking | Embedded payroll can be integrated with time-tracking systems to automate pay calculations based on hours worked, overtime, and PTO. |
| Expense management | Gusto APIs can automate expense reimbursement processes by linking the expense management systems with payroll systems. |
Follow Best Practices for Secure Payroll API Integration
When integrating payroll APIs, developers need to make sure that their system is designed to handle authentication, rate limits, and API errors. These best practices help ensure smooth integrations and protect sensitive data:
| Rate limiting | This ensures that the application batches or throttles API requests to avoid hitting the rate limits. The Gusto API rate limit is 200 requests per minute, and subsequent requests will be rejected with a 429: Too Many Requests status code. |
| Error handling | Your application should gracefully handle error responses to reduce unexpected user behavior. Gusto APIs provide consistent JSON error responses with proper error_key, category, and message containing relevant details about the error. Refer to the error categories guide to learn more about the list of errors these APIs return. |
| Security | Because payroll data is sensitive, API integrations require OAuth authentication, and all sensitive data should be handled and stored securely. |
Conclusion
Payroll APIs make it easier for businesses and SaaS developers to offer payroll without needing to build it from scratch – and take advantage of existing employee data that’s already stored on the platform. Likewise, developers can leverage the embedded payroll APIs to extract data and offer customers a more complete picture of their finances. These APIs provide access to employee, compensation, attendance, taxation, and payroll data, enabling businesses to seamlessly integrate and sync data across financial, HR, and accounting systems.
Gusto Embedded is an all-in-one payroll system that enables businesses to embed and customize payroll directly in their software using flexible payroll APIs. Rather than a one-way payroll integration, Gusto Embedded enables you to offer a full-service payroll experience natively within the app, driving engagement and unlocking new revenue opportunities. The developer-friendly APIs save time, reduce errors, and help you gain deeper insights. As payroll runs, you can programmatically access payroll data via its comprehensive set of APIs to support customized workflows, analytics, and integration with other systems.
