Gusto is an online payroll and HR solutions company. Backed by global expertise Gusto provides companies with one easy, integrated platform, to automate and simplify payroll, benefits, and HR processes. From time tracking, to performance management, analytics and even benefits administration, Gusto application enables businesses to make HR management seamless and streamlined, while saving hours and reducing human errors considerably.
Gusto API Authentication, Pagination, Rate Limits
As a security first application, Gusto leverages OAuth2 for authentication. Gusto API integration uses two types of tokens for security and authentication. On the one side are organization level API tokens which can be accessed through the Developer Portal. Additionally, there are company level tokens (generally access tokens or refresh tokens), which are provided via the OAuth2 process. It is very important for developers building integrations with Gusto API to manage, store and maintain all tokens securely to prevent unauthorized authentication and access.
Essentially, API tokens are used specifically for organization level endpoints, like creating a company, and cannot be used for company or employee level endpoints. For the latter, developers must focus on access tokens via OAuth2. To facilitate higher levels of security, Gusto API ensures that all endpoints which are authenticated via access tokens require a strict access token, which is reserved for access only to a single company.
Gusto API endpoints support pagination. To use pagination, developers can add a page and a per parameter to their URL’s query string. The page can define the page number from where records are sought, and the per parameter dictates the number of records per page. In case the per parameter is left blank, by default 25 records will be returned. Each endpoint’s documentation reflects on whether or not it supports pagination.
To ensure high performance throughput, Gusto API maintains an API rate limit of 200 requests per minute. This suggests that 200 API calls can be made within the 60 second time window, beyond which a violation will be evaluated. A 429 error, highlighting too many requests will be displayed if the rate limit is hit for an active integration and the request will be subsequently rejected.
Gusto API Objects, Data Models & Endpoints
An understanding of the Gusto API objects, data models and endpoints is extremely important for developers seeking to build integrations with Gusto API. Some of the key endpoints include:
Companies
- Create a company
POST https://api.gusto-demo.com/v1/provision
- Get a company
GET https://api.gusto-demo.com/v1/companies/{company_id}
- Get the custom fields of a company
GET https://api.gusto-demo.com/v1/companies/{company_id}/custom_fields
Locations
- Create a company location
POST https://api.gusto-demo.com/v1/companies/{company_id}/locations
- Get company locations
GET https://api.gusto-demo.com/v1/companies/{company_id}/locations
- Get a location
GET https://api.gusto-demo.com/v1/locations/{location_id}
- Update a location
PUT https://api.gusto-demo.com/v1/locations/{location_id}
- Get minimum wages for a location
GET https://api.gusto-demo.com/v1/locations/{location_uuid}/minimum_wages
Pay Schedules
- Get the pay schedules for a company
GET https://api.gusto-demo.com/v1/companies/{company_id}/pay_schedules
- Get a pay schedule
GET https://api.gusto-demo.com/v1/companies/{company_id}/pay_schedules/{pay_schedule_id}
- Get pay periods for a company
GET https://api.gusto-demo.com/v1/companies/{company_id}/pay_periods
- Get pay schedule assignments for a company
GET https://api.gusto-demo.com/v1/companies/{company_id}/pay_schedules/assignments
Departments
- Create a department
POST https://api.gusto-demo.com/v1/companies/{company_uuid}/departments
- Get all departments of a company
GET https://api.gusto-demo.com/v1/companies/{company_uuid}/departments
- Get a department
GET https://api.gusto-demo.com/v1/departments/{department_uuid}
- Update a department
PUT https://api.gusto-demo.com/v1/departments/{department_uuid}
- Delete a department
DELETE https://api.gusto-demo.com/v1/departments/{department_uuid}
- Add people to a department
PUT https://api.gusto-demo.com/v1/departments/{department_uuid}/add
- Remove people from a department
PUT https://api.gusto-demo.com/v1/departments/{department_uuid}/remove
Earning Types
- Create a custom earning type
POST https://api.gusto-demo.com/v1/companies/{company_id}/earning_types
- Get all earning types for a company
GET https://api.gusto-demo.com/v1/companies/{company_id}/earning_types
- Update an earning type
PUT https://api.gusto-demo.com/v1/companies/{company_id}/earning_types/{earning_type_uuid}
- Deactivate an earning type
DELETE https://api.gusto-demo.com/v1/companies/{company_id}/earning_types/{earning_type_uuid}
Payrolls
- Get all payrolls for a company
GET https://api.gusto-demo.com/v1/companies/{company_id}/payrolls
- Get a single payroll
GET https://api.gusto-demo.com/v1/companies/{company_id}/payrolls/{payroll_id}
- Update a payroll by ID
PUT https://api.gusto-demo.com/v1/companies/{company_id}/payrolls/{payroll_id}
- Prepare a payroll for update
PUT https://api.gusto-demo.com/v1/companies/{company_id}/payrolls/{payroll_id}/prepare
Contractor Payments
- Get contractor payments for a company
GET https://api.gusto-demo.com/v1/companies/{company_id}/contractor_payments
- Get a single contractor payment
GET https://api.gusto-demo.com/v1/companies/{company_id}/contractor_payments/{contractor_payment_id}
Company Benefits
- Create a company benefit
POST https://api.gusto-demo.com/v1/companies/{company_id}/company_benefits
- Get benefits for a company
GET https://api.gusto-demo.com/v1/companies/{company_id}/company_benefits
- Get a company benefit
GET https://api.gusto-demo.com/v1/company_benefits/{company_benefit_id}
- Update a company benefit
PUT https://api.gusto-demo.com/v1/company_benefits/{company_benefit_id}
- Delete a company benefit
DELETE https://api.gusto-demo.com/v1/company_benefits/{company_benefit_id}
- Get all benefits supported by Gusto
GET https://api.gusto-demo.com/v1/benefits
- Get a supported benefit by ID
GET https://api.gusto-demo.com/v1/benefits/{benefit_id}
- Get company benefit summary by company benefit id.
GET https://api.gusto-demo.com/v1/company_benefits/{company_benefit_id}/summary
- Get benefit fields requirements by ID
GET https://api.gusto-demo.com/v1/benefits/{benefit_id}/requirements
Employees
- Create an employee
POST https://api.gusto-demo.com/v1/companies/{company_id}/employees
- Get employees of a company
GET https://api.gusto-demo.com/v1/companies/{company_id}/employees
- Get an employee
GET https://api.gusto-demo.com/v1/employees/{employee_id}
- Update an employee
PUT https://api.gusto-demo.com/v1/employees/{employee_id}
- Delete an onboarding employee
DELETE https://api.gusto-demo.com/v1/employees/{employee_id}
- Get an employee's custom fields
GET https://api.gusto-demo.com/v1/employees/{employee_id}/custom_fields
- Get employee time off activities
GET https://api.gusto-demo.com/v1/employees/{employee_uuid}/time_off_activities
Employee Employments
- Get terminations for an employee
GET https://api.gusto-demo.com/v1/employees/{employee_id}/terminations
- Get an employee rehire
GET https://api.gusto-demo.com/v1/employees/{employee_id}/rehire
- Get employment history for an employee
GET https://api.gusto-demo.com/v1/employees/{employee_id}/employment_history
Employee Addresses
- Get an employee's home addresses
GET https://api.gusto-demo.com/v1/employees/{employee_id}/home_addresses
- Create an employee's home address
POST https://api.gusto-demo.com/v1/employees/{employee_id}/home_addresses
- Get an employee's home address
GET https://api.gusto-demo.com/v1/home_addresses/{home_address_uuid}
- Update an employee's home address
PUT https://api.gusto-demo.com/v1/home_addresses/{home_address_uuid}
- Delete an employee's home address
DELETE https://api.gusto-demo.com/v1/home_addresses/{home_address_uuid}
- Get an employee's work addresses
GET https://api.gusto-demo.com/v1/employees/{employee_id}/work_addresses
- Create an employee work address
POST https://api.gusto-demo.com/v1/employees/{employee_id}/work_addresses
- Get an employee work address
GET https://api.gusto-demo.com/v1/work_addresses/{work_address_uuid}
- Update an employee work address
PUT https://api.gusto-demo.com/v1/work_addresses/{work_address_uuid}
- Delete an employee's work address
DELETE https://api.gusto-demo.com/v1/work_addresses/{work_address_uuid}
Jobs and Compensations
- Create a job
POST https://api.gusto-demo.com/v1/employees/{employee_id}/jobs
- Get jobs for an employee
GET https://api.gusto-demo.com/v1/employees/{employee_id}/jobs
- Get a job
GET https://api.gusto-demo.com/v1/jobs/{job_id}
- Update a job
PUT https://api.gusto-demo.com/v1/jobs/{job_id}
- Delete an individual job
DELETE https://api.gusto-demo.com/v1/jobs/{job_id}
- Get compensations for a job
GET https://api.gusto-demo.com/v1/jobs/{job_id}/compensations
- Create a compensation
POST https://api.gusto-demo.com/v1/jobs/{job_id}/compensations
- Get a compensation
GET https://api.gusto-demo.com/v1/compensations/{compensation_id}
- Update a compensation
PUT https://api.gusto-demo.com/v1/compensations/{compensation_id}
- Delete a compensation
DELETE https://api.gusto-demo.com/v1/compensations/{compensation_id}
Employee Benefits
- Create an employee benefit
POST https://api.gusto-demo.com/v1/employees/{employee_id}/employee_benefits
- Get all benefits for an employee
GET https://api.gusto-demo.com/v1/employees/{employee_id}/employee_benefits
- Get an employee benefit
GET https://api.gusto-demo.com/v1/employee_benefits/{employee_benefit_id}
- Update an employee benefit
PUT https://api.gusto-demo.com/v1/employee_benefits/{employee_benefit_id}
- Delete an employee benefit
DELETE https://api.gusto-demo.com/v1/employee_benefits/{employee_benefit_id}
- Create year-to-date benefit amounts from a different company
POST https://api.gusto-demo.com/v1/employees/{employee_id}/ytd_benefit_amounts_from_different_company
Garnishments
- Create a garnishment
POST https://api.gusto-demo.com/v1/employees/{employee_id}/garnishments
- Get garnishments for an employee
GET https://api.gusto-demo.com/v1/employees/{employee_id}/garnishments
- Get a garnishment
GET https://api.gusto-demo.com/v1/garnishments/{garnishment_id}
- Update a garnishment
PUT https://api.gusto-demo.com/v1/garnishments/{garnishment_id}
Gusto API Use Cases
- Automate employee time tracking (with flexible scheduling and remote work options), approval and accurate payroll creation
- Rely on robust and customizable checklists for employee onboarding and ensure software provisioning with a few clicks
- Automate workflow for performance management including self evaluation, manager review and career development sources with custom performance software
- Leverage customizable reports, anonymous team surveys, automatic compliance alerts for holistic team insights
- Create a payroll which runs on autopilot with automated calculations, compliances and much more
Top customers
Serving 300,000+ businesses, Gusto API is the preferred HR and payroll solutions provider for many global names, including:
- Little Fish Accounting, a boutique CPA firm providing small businesses, entrepreneurs, and freelancers with accounting + tax support
- ApproveMe.com, a document signing experience™ that helps businesses build better relationships with their signers
- Snapbar, a company that develops intuitive, web-based products leveraging the power of photo and video
- Heckler Design, a firm that creates beautifully simple, commercial-grade hardware and furniture for design-conscious consumers and businesses
- Floyd Lee Locums, a company that provides an elite concierge experience to physicians, CRNAs, nurse practitioners, physician assistants, and other healthcare providers
Gusto API FAQs
Following is a list of FAQs that can help guide your Gusto API integration journey:
- How do I get access to a sandbox environment to build Gusto API integration? Answer
- How do I get API keys for Gusto API? Answer
- Can I change the redirect URI for the API Keys? Answer
- How long does it usually take to build an integration with Gusto API? Answer
- Once an employee is created in Gusto via the API, what happens next? Answer
- What’s required to obtain API Keys for Production? Answer
- What debits can I expect to see via the Gusto API? Answer
- Can I make test calls in production after my Gusto API integration has passed QA and launched? Answer
- What are the error codes associated with Gusto API? Answer
- How can I create a job ID and compensation for an employee in Gusto API? Answer
- Does Gusto API have any sample codes I can use to get started on? Answer
- What kind of support will I get when building my integration? Answer
Common Integrations with Gusto API
Undoubtedly, there are several categories of applications which can benefit from integrating with Gusto API. Listing a few for developers to get an idea:
- ATS applications to push newly hired candidate data
- Performance management systems to get access to employee rosters and information
- HR analytics platforms to get access to employee data, including payroll, compensation, etc.
- Benefits applications to facilitate accurate deductions and benefits administration
How to integrate with Gusto API
To commence your integration journey with Gusto API, it is important to create a developer account. You can sign up for an account here. Once you sign up for a developer account, the next steps are quite streamlined. It involves accepting the terms of service, setting up the account, creating the application to get access to your unique Gusto API keys. As a best practice, it is ideal to go through the detailed documentation and guides offered by Gusto API to understand the diverse aspects of integration. You can check out the documentation resource to answer all questions you may have, here. Gusto API also offers a sandbox functionality to test and demo your work, before making a firm commitment.
Get started with Gusto API
Developers can build Gusto API integration for their applications following the steps mentioned in the section above and by leveraging the documentation shared. However, building one integration can take up to 4-6 weeks on an average, utilizing a lot of developer bandwidth, becoming a cost intensive project. In case you need to build more than one HRMS integration, leveraging a unified API like Knit is ideal. A unified API adds an additional layer of abstraction on top of the API, ensuring that developers only have to integrate with one unified API to connect with several HRMS applications supported by the unified API. To understand how a unified API like Knit can help your integration journey, book a demo today.
.jpg)
.png)
.png)
.png)
