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.<\/p>\n
![\"Mocked](\"https:\/\/embeddedblog.wpengine.com\/wp-content\/uploads\/2025\/09\/EMB-blog-api-capabilities-inline-425x238.png\")
<\/p>\n
<\/p>\n
Access Payroll Data Through APIs<\/h2>\n
Gusto Embedded provides comprehensive APIs to access all kinds of employee data, including compensation data, time and attendance data, and payroll processing data.<\/p>\n
Employee Data<\/h3>\n
Employee APIs help access and manage employee data, including full name, date of birth, contact details, employment status, and job title. For instance, the The following code snippet shows a request to get an employee’s data:<\/p>\n The API returns a response containing employee data like this:<\/p>\n Compensation APIs help manage salary and wage details for employees. For instance, the The following code snippet shows a request to get compensation details using the The API returns a response containing wage data like this:<\/p>\n Similarly, you can use the POST 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 The following code snippet shows a request to get the time-off activities for an employee using the The API returns a response containing employee time-off activities:<\/p>\n Gusto also provides API endpoints to granularly manage and view time-off policies<\/a>.<\/p>\n 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 The following code snippet shows a request to get the federal tax attributes for an employee using the The API returns a response containing the employee’s federal tax attributes:<\/p>\n Similarly, the 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 The following code snippet shows a request to get the payroll receipt using the The API returns a response containing the tax and compensation details for the specified payroll UUID:<\/p>\n Gusto provides a comprehensive set of API endpoints to manage and view payroll data<\/a> and offers APIs that integrate with external payrolls<\/a>.<\/p>\n Vagaro<\/a> 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.<\/p>\n Recently, Vagaro integrated the Gusto Embedded Payroll API<\/a> 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.<\/p>\n To learn more about how Vagaro uses Gusto Embedded, check out this interview with Fred Helou<\/a> and watch a recording of the webinar<\/a> that features Vagaro customer Cassidee, owner of Golden State Strands Salon.<\/p>\n 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:<\/p>\n Before calling any payroll API, you need to obtain a company access token, as illustrated in this diagram:<\/p>\n The Gusto Getting Started<\/strong> guide<\/a> describes the authentication process in detail, but here are the broad steps you need to follow:<\/p>\n The API returns the company UUID, access token, and refresh token, as shown here:<\/p>\n You need to pass this Payroll APIs let you fetch detailed employee information, including personal data, payroll status, and compensation history:<\/p>\n By default, the API returns only the current compensation:<\/p>\n 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.<\/p>\n The POST The API returns the details of the newly created payroll:<\/p>\n Additionally, an existing payroll can be updated using the PUT The API returns the details of the updated payroll:<\/p>\n 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 Additionally, Gusto provides APIs to store and retrieve I-9 documents<\/a>, as well as signatures and other information required to complete the I-9 form for employment eligibility verification.<\/p>\n The PUT The GET The API returns only the I-9 authorization details:<\/p>\n 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<\/a>, allowing you to receive real-time notifications when key payroll events occur, such as new hires, terminations, or pay runs.<\/p>\n Employee events<\/a> notify you of different events, such as For example, when an employee is added to the company’s payroll, a webhook Other internal systems can subscribe to these events to sync employee records, grant tooling access, and create accounts. You can configure webhooks<\/a> using the Gusto developer portal.<\/p>\n Developer-friendly and comprehensive Gusto Payroll APIs can be used to build custom solutions, including the following:<\/p>\n\/v1\/employees\/{employee_id}<\/code><\/a> endpoint can be used to retrieve an employee’s details.<\/p>\ncurl --request GET \\\n --url https:\/\/api.gusto-demo.com\/v1\/employees\/123 \\\n --header 'X-Gusto-API-Version: 2024-04-01' \\\n --header 'accept: application\/json' \\\n --header 'authorization: Bearer YOUR_TOKEN'\n<\/code><\/pre>\n{\n "uuid": "d59f0776-107e-4c43-a148-564a14c8cdbf",\n "first_name": "Kurtis",\n "last_name": "McKenzie",\n "company_uuid": "cc82c11f-d4ba-4f55-aace-2fb7b1fefa1f",\n "onboarding_status": "onboarding_completed",\n ...\n "jobs": [\n {\n ...\n "title": "Engineer",\n "hire_date": "2025-05-16",\n "location": {\n "uuid": "3ee20a56-8931-47f4-94c7-e637dda8cf74",\n ...\n "zip": "94107",\n "country": "USA",\n "inactive": false\n }\n }\n ],\n ...\n "date_of_birth": "2005-05-16"\n}\n<\/code><\/pre>\nCompensation Data<\/h3>\n
\/v1\/compensations\/{compensation_id}<\/code><\/a> endpoint can be used to fetch information about how much an employee is paid for a job.<\/p>\ncompensation_id<\/code>:<\/p>\ncurl --request GET \\\n --url https:\/\/api.gusto-demo.com\/v1\/compensations\/x123 \\\n --header 'X-Gusto-API-Version: 2024-04-01' \\\n --header 'accept: application\/json' \\\n --header 'authorization: Bearer YOUR_TOKEN'\n<\/code><\/pre>\n{\n "uuid": "db57832c-d8bc-43a7-ae99-0a04480ff037",\n "version": "98jr3289h3298hr9329gf9egskt3kagri32qqgiqe3872",\n "job_uuid": "d8f8fbe7-496d-4b69-86f0-1e2d1b73a086",\n "rate": "60000.00",\n "payment_unit": "Year",\n "flsa_status": "Exempt",\n "effective_date": "2025-05-11",\n "adjust_for_minimum_wage": false,\n "minimum_wages": []\n}\n<\/code><\/pre>\n\/v1\/jobs\/{job_id}\/compensations<\/code><\/a> endpoint to create compensation for a job.<\/p>\nTime and Attendance Data<\/h3>\n
\/v1\/employees\/{employee_uuid}\/time_off_activities<\/code><\/a> endpoint returns the time-off details for an employee.<\/p>\nemployee_id<\/code>:<\/p>\ncurl --request GET \\\n --url https:\/\/api.gusto-demo.com\/v1\/employees\/123\/time_off_activities \\\n --header 'X-Gusto-API-Version: 2024-04-01' \\\n --header 'accept: application\/json' \\\n --header 'authorization: Bearer YOUR_TOKEN'\n<\/code><\/pre>\n[\n {\n "policy_uuid": "a7838f74-4c29-4b70-9bfb-02a4e3e60709",\n "time_off_type": "vacation",\n "policy_name": "Paid Time Off",\n "event_type": "TimeOffEvent::AddToPolicy",\n "event_description": "Added to policy: Vacation Per Hour Worked",\n "effective_time": "2025-05-27T13:43:03.000-07:00",\n "balance": "0.0",\n "balance_change": "0.0"\n },\n ...\n]\n<\/code><\/pre>\nTax and Compliance Data<\/h3>\n
\/v1\/employees\/{employee_uuid}\/federal_taxes<\/code><\/a> endpoint returns the attributes relevant to an employee’s federal taxes.<\/p>\nemployee_id<\/code>:<\/p>\ncurl --request GET \\\n --url https:\/\/api.gusto-demo.com\/v1\/employees\/123\/federal_taxes \\\n --header 'X-Gusto-API-Version: 2024-04-01' \\\n --header 'accept: application\/json' \\\n --header 'authorization: Bearer YOUR_TOKEN'\n<\/code><\/pre>\n{\n "version": "56a489ce86ed6c1b0f0cecc4050a0b01",\n "filing_status": "Single",\n "extra_withholding": "0.0",\n "two_jobs": true,\n "dependents_amount": "0.0",\n "other_income": "0.0",\n "deductions": "0.0",\n "employee_id": 29,\n "w4_data_type": "rev_2025_w4"\n}\n<\/code><\/pre>\n\/v1\/employees\/{employee_uuid}\/state_taxes<\/code><\/a> 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<\/a> details needed by US federal law for employment eligibility verification.<\/p>\nPayroll Processing Data<\/h3>\n
\/v1\/payrolls\/{payroll_uuid}\/receipt<\/code><\/a> endpoint returns a payroll receipt with compensation and tax information.<\/p>\npayroll_uuid<\/code>:<\/p>\ncurl --request GET \\\n --url https:\/\/api.gusto-demo.com\/v1\/payrolls\/payroll_uuid\/receipt \\\n --header 'X-Gusto-API-Version: 2024-04-01' \\\n --header 'accept: application\/json' \\\n --header 'authorization: Bearer YOUR_TOKEN'\n<\/code><\/pre>\n{\n "totals": {\n "company_debit": "1080.47",\n ...\n },\n "taxes": [\n {\n "name": "Federal Income Tax",\n "amount": "30.36"\n },\n ...\n ],\n "employee_compensations": [\n {\n "employee_uuid": "f83d0bd8-7e20-43b9-834c-6d514ef6cb47",\n "employee_first_name": "Patricia",\n "employee_last_name": "Hamill",\n "payment_method": "Direct Deposit",\n "net_pay": "748.34",\n "total_tax": "182.13",\n ...\n }\n ],\n "licensee": {\n "name": "Gusto, Zenpayroll Inc.",\n "address": "525 20th St",\n ...\n },\n "payroll_uuid": "afccb970-357e-4013-81f5-85dafc74f9b6",\n "company_uuid": "c827aa0d-3928-4d5a-ab1f-400641a7d2b8",\n "name_of_sender": "Torp and Sons and Sons",\n "name_of_recipient": "Payroll Recipients",\n ...\n}\n<\/code><\/pre>\nHow One Partner Uses the Gusto Embedded Payroll API for a Seamless User Experience<\/h2>\n
Use Core API Operations for Payroll Management<\/h2>\n
\n
Manage Authentication and Security<\/h3>\n
![\"Gusto](\"https:\/\/i.imgur.com\/DtlscEW.png\")
<\/p>\n\n
client_id<\/code> and client_secret<\/code>.<\/li>\n\/oauth\/token<\/code><\/a> endpoint using the client ID and secret to obtain a system access_token<\/code>, which is valid for two hours.<\/li>\n\/v1\/partner_managed_companies<\/code><\/a> endpoint using the system access_token<\/code> to create a new company. For example, here’s the code snippet to create a company:<\/li>\n<\/ul>\ncurl --request POST \\\n --url https:\/\/api.gusto-demo.com\/v1\/partner_managed_companies \\\n --header 'X-Gusto-API-Version: 2024-04-01' \\\n --header 'accept: application\/json' \\\n --header 'authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \\\n --header 'content-type: application\/json'\n<\/code><\/pre>\n{\n "access_token": "de6780bc506a0446309bd9362820ba8aed28aa506c71eedbe1c5c4f9dd350e54",\n "refresh_token": "8257e65c97202ed1726cf9571600918f3bffb2544b26e00a61df9897668c33a1",\n "company_uuid": "d525dd21-ba6e-482c-be15-c2c7237f1364",\n "expires_in": 7200\n}\n<\/code><\/pre>\naccess_token<\/code> with every payroll API request. Notice that the access expires in two hours. You can exchange the refresh_token<\/code> for a new access token using the OAuth token<\/a> API. The previous refresh_token<\/code> will be revoked on the first usage of the new access_token<\/code>.<\/p>\nRetrieve Employee Data<\/h3>\n
\n
\/v1\/employees\/{employee_id}<\/code><\/a> endpoint to fetch employee details based on an employee_id<\/code>. In addition to personal details, this API also returns a list of jobs<\/code> associated with the employee.<\/li>\n\/v1\/employees\/{employee_id}\/pay_stubs<\/code><\/a> endpoint to fetch an employee’s pay stub history.<\/li>\nGET<\/code> \/v1\/jobs\/{job_id}\/compensations<\/code><\/a> endpoint, 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 specified job_id<\/code>:<\/li>\n<\/ul>\ncurl --request GET \\\n --url https:\/\/api.gusto-demo.com\/v1\/jobs\/123\/compensations \\\n --header 'X-Gusto-API-Version: 2024-04-01' \\\n --header 'accept: application\/json' \\\n --header 'authorization: Bearer YOUR_TOKEN'\n<\/code><\/pre>\n[\n {\n "id": 1363316536327003,\n "job_id": 1123581321345589,\n ...\n "payment_unit": "Hour",\n "flsa_status": "Nonexempt",\n "effective_date": "2018-12-11",\n "rate": "5.00",\n "adjust_for_minimum_wage": true,\n "minimum_wages": [\n {\n "uuid": "edeea5af-ecd6-4b1c-b5de-5cff2d302738",\n "wage": "7.25",\n "effective_date": "2025-05-11"\n }\n ]\n }\n ...\n]\n<\/code><\/pre>\nCreate and Update Payroll Records<\/h3>\n
\/v1\/companies\/{company_id}\/payrolls<\/code><\/a> 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<\/code>:<\/p>\ncurl --request POST \\\n --url https:\/\/api.gusto-demo.com\/v1\/companies\/{company_id}\/payrolls \\\n --header 'X-Gusto-API-Version: 2024-04-01' \\\n --header 'accept: application\/json' \\\n --header 'authorization: Bearer YOUR_TOKEN' \\\n --header 'content-type: application\/json' \\\n --data '{"off_cycle": true, "off_cycle_reason": "Bonus"}'\n<\/code><\/pre>\n{\n "version": "19289df18e6e20f797de4a585ea5a91535c7ddf7",\n "payroll_deadline": "2022-02-18T22:00:00Z",\n "check_date": "2025-02-22",\n "off_cycle": true,\n ...\n "uuid": "b50e611d-8f3d-4f24-b001-46675f7b5777",\n "payroll_uuid": "b50e611d-8f3d-4f24-b001-46675f7b5777",\n "company_uuid": "6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb",\n "created_at": "2025-02-01T22:00:00Z",\n "pay_period": {\n "start_date": "2025-02-01",\n "end_date": "2025-02-15",\n "pay_schedule_uuid": "00ebc4a4-ec88-4435-8f45-c505bb63e501"\n },\n ...\n}\n<\/code><\/pre>\n\/v1\/companies\/{company_id}\/payrolls\/{payroll_id}<\/code><\/a> endpoint. For example, the following code snippet shows a request that updates a payroll for the specified company_id<\/code> and payroll_id<\/code>:<\/p>\ncurl --request PUT \\\n --url https:\/\/api.gusto-demo.com\/v1\/companies\/{company_id}\/payrolls\/{payroll_id} \\\n --header 'X-Gusto-API-Version: 2024-04-01' \\\n --header 'accept: application\/json' \\\n --header 'authorization: Bearer YOUR_TOKEN' \\\n --header 'content-type: application\/json' \\\n --data '{"withholding_pay_period": "Twice per month", "fixed_withholding_rate": true}'\n<\/code><\/pre>\n{\n "payroll_deadline": "2022-02-18T22:00:00Z",\n "uuid": "b50e611d-8f3d-4f24-b001-46675f7b5777",\n "payroll_uuid": "b50e611d-8f3d-4f24-b001-46675f7b5777",\n "company_uuid": "6bf7807c-a5a0-4f4d-b2e7-3fbb4b2299fb",\n "created_at": "2022-02-01T22:00:00Z",\n "pay_period": {\n "start_date": "2025-02-01",\n "end_date": "2025-02-15",\n "pay_schedule_uuid": "00ebc4a4-ec88-4435-8f45-c505bb63e501"\n },\n ...\n}\n<\/code><\/pre>\nAddress Tax Calculations and Compliance Reporting<\/h3>\n
\/v1\/companies\/{company_id}\/payrolls\/{payroll_id}\/calculate<\/code><\/a> endpoint can be used to perform calculations for taxes, benefits, and deductions for an unprocessed payroll.<\/p>\n\/v1\/employees\/{employee_id}\/i9_authorization<\/code><\/a> endpoint stores information about an employee’s authorization status.<\/p>\n\/v1\/employees\/{employee_id}\/i9_authorization<\/code><\/a> 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:<\/p>\ncurl --request GET \\\n --url https:\/\/api.gusto-demo.com\/v1\/employees\/123\/i9_authorization \\\n --header 'X-Gusto-API-Version: 2024-04-01' \\\n --header 'accept: application\/json' \\\n --header 'authorization: Bearer YOUR_TOKEN'\n<\/code><\/pre>\n[\n {\n "version": "6ae7ff720107b356bf13b1606f60b24f",\n "uuid": "7f2337f9-9b78-44b9-aeed-be4777b833a8",\n "form_uuid": "c54046f7-1be4-4c54-8194-f4842c30c86d",\n "authorization_status": "alien",\n "document_type": "foreign_passport",\n "has_document_number": true,\n "expiration_date": "2027-01-01",\n "country": "Panama",\n "employer_signed": false,\n "employee_signed": false,\n "additional_info": "Notes",\n "alt_procedure": false\n }\n]\n<\/code><\/pre>\nHandle Webhooks for Real-Time Updates<\/h3>\n
created<\/code>, updated<\/code>, onboarded<\/code>, and terminated<\/code>. These webhooks can be used to automate employee onboarding and offboarding data syncs across internal systems.<\/p>\nemployee.created<\/code> event will be triggered:<\/p>\n{\n "uuid": "03ffbf0c-48a9-4f1c-932a-546413a26ad1",\n "event_type": "employee.created",\n "resource_type": "Company",\n "resource_uuid": "5df911a0-e8e9-412d-8aaf-a46ad193dd96",\n "entity_type": "Employee",\n "entity_uuid": "bcfc9744-0ab3-4ef3-ab0d-e728255d659c",\n "timestamp": 1671058841\n}\n<\/code><\/pre>\nBuild Custom Solutions with Payroll APIs<\/h2>\n