Gusto API Essential Guide

What type of API does Gusto provide?

Based on the search results provided, Gusto appears to have a REST API. The documentation style and terminology used, such as discussing API scopes, endpoints, and HTTP status codes, are typical of REST API documentation. Additionally, none of the search results mention Gusto using GraphQL, SOAP, or other API types. REST APIs are widely used for web services due to their simplicity, scalability, and compatibility with HTTP.

Does the Gusto API have webhooks?

Yes, the official Gusto API does have webhooks. Here are the key points about Gusto's webhook functionality:

Webhook Support

The Gusto API provides webhook support, allowing you to subscribe to various events and receive real-time notifications when those events occur.

Event Types

You can subscribe to a wide range of event types through Gusto's webhooks. Some of the main categories of events include:

• Bank Account events
• Company events
• Company Benefit events
• Contractor events
• Contractor Payment events
• Employee events
• Employee Benefit events
• Employee Job Compensation events
• External Payroll events
• Form events
• Location events
• Payroll events
• Pay Schedule events

Specific Event Examples

Here are some specific examples of events you can subscribe to:

• Bank Account: created, updated, deleted
• Company: provisioned, updated, onboarded, approved, partner_authorized
• Contractor: created, updated, onboarded, deactivated, deleted
• Employee: created, updated, onboarded, terminated, deleted
• Payroll: created, updated, calculated, submitted, processed, paid, reversed, cancelled

Managing Webhook Subscriptions

The Gusto API provides endpoints for managing webhook subscriptions, including:

• Creating a webhook subscription
• Listing webhook subscriptions
• Updating a webhook subscription
• Getting a specific webhook subscription
• Deleting a webhook subscription
• Verifying a webhook subscription

Authentication

Webhook-related API calls typically require system-level access authentication using the Bearer Auth scheme with a system-level access token in the HTTP Authorization header.

By using Gusto's webhook functionality, you can build integrations that respond in real-time to changes in payroll, employee, and company data, enabling more efficient and automated workflows.

Rate Limits and other limitations

Here are the key points about the API Rate Limits for the Gusto API:

Rate Limit Details

• The Gusto API rate limit is 200 requests per minute [1][2][3].

• Rate limits are evaluated using a 60 second rolling window [2][3].

• The rate limit is applied at the user-application pair level, meaning you can make up to 200 calls within a 60 second timeframe for each user with an active integration [2].

• For users authorizing an integration for multiple companies, the rate limit is shared amongst those companies [2].

Exceeding the Rate Limit

• If the rate limit is exceeded, subsequent requests will be rejected with a 429: Too Many Requests status code until the violating window closes [2][3].

Key Considerations

• The rate limit is per user/company that has connected your application, not a global limit across all users [3].

• A new 60-second window opens after your first API call and closes after 60 seconds has elapsed. A new window opens when you send your next API request [3].

• It's important to design your application to handle rate limit errors gracefully and implement appropriate retry mechanisms.

Best Practices

• Monitor your API usage to ensure you stay within the rate limits.

• Implement exponential backoff and retry logic for handling rate limit errors.

• Consider caching frequently accessed data to reduce the number of API calls needed.

• Optimize your API usage by batching requests where possible and avoiding unnecessary calls.

By adhering to these rate limits and implementing best practices, you can ensure smooth integration with the Gusto API while maintaining good performance and avoiding disruptions due to rate limiting.

Latest API Version

Based on the search results provided, here is the answer to your question about the most recent version of the Gusto API:

The most recent version of the Gusto API is v2024-04-01.

Key points to consider:

1. Gusto uses a date-based versioning system for their API [^2].

2. Versions prior to v2023-09-01 have been deprecated ^1.

3. The API version v2024-04-01 introduced system access tokens, deprecating API Token auth in favor of system access authentication ^1.

4. Gusto may release new versions as often as monthly, but sometimes consolidates smaller changes into larger subsequent releases [^2].

5. After a version is released, it is guaranteed to receive support for a minimum of 12 months from the version date [^2].

Best practices:

1. Always use the latest stable version of the API when possible.

2. Gusto strongly advises upgrading to the latest API version every quarter for improved performance and security [^2].

3. Set the API version by including an 'X-Gusto-API-Version' header in your API calls [^3].

4. Stay informed about API updates by regularly checking the Changelog [^2].

5. Be aware of backward-incompatible changes that may require updates to your integration [^2][^3].

Remember to check the Gusto Developer Documentation for the most up-to-date information on API versions and best practices for integration.

[^2]: API Versioning [^3]: API Versioning v1.0.0

How to get a Gusto developer account and API Keys?

1. Sign up for a Developer Portal account

The first step is to create an account on Gusto's Developer Portal. This is essential for accessing the API and beginning the development process.

2. Complete the Production Pre-Approval application

After creating your Developer Portal account, you need to fill out a Production Pre-Approval application. This step is crucial as it's required to go through QA and gain production access.

Key points to consider:

• The information collected during the pre-approval process will be handled according to Gusto's Developer Terms.
• An approved Production Pre-Approval and Security Review are necessary for production access.

3. Set up your Organization and obtain API token

Once your account is created and you've completed the Organization setup, you'll have access to your unique API token from the Organizations tab. This token is used for provisioning new Gusto accounts.

4. Create an application and obtain API credentials

To access Gusto's demo environment, you need to create an application in the Developer Portal. This will provide you with:

• A unique client_id
• A secret for authentication

Note: When creating an application, you'll need to provide at least one redirect URI.

5. Create a demo company

Create a demo company to explore Gusto's product and connect your application via OAuth2. Demo companies are automatically generated with company info, employees, and previous payrolls for testing purposes.

6. Begin development

With your API Token, client_id, secret, and a demo company set up, you can start building your integration.

7. Review and QA process

Before getting production keys, Gusto requires a quality review (QA) and an approved Production Pre-Approval application for all builds using their API. This ensures proper functionality and a high-quality customer experience.

Best practices:

1. Use the sandbox environment (https://api.gusto-demo.com) for initial development and testing.
2. If you're an app developer, request viewing access to the Partner Checklist for scoping your build and submitting it for review.
3. Be prepared to have your application assigned API scopes based on your integration use-case during the review process.
4. After approval, you can request additional scopes or changes by contacting [email protected].

Remember, Gusto currently does not support API access for customers looking to connect their own company systems directly to their Gusto account using the API.

What can you do with the Gusto API?

Based on the search results provided, here is a list of data models that can be interacted with using the Gusto API, along with what is possible for each:

Employee Data

• Create new employees
• Update employee information
• Access employee rosters and details
• Manage employee onboarding processes

Payroll Data

• Run payroll calculations
• Create and manage payroll schedules
• Access payroll information for reporting and analytics

Time Tracking

• Automate employee time tracking
• Manage flexible scheduling and remote work options
• Approve time entries

Compensation Data

• Create and manage job IDs and compensation information
• Access compensation data for reporting and analytics

Benefits Administration

• Facilitate benefits deductions
• Manage benefits administration

Performance Management

• Access employee performance data
• Manage self-evaluations and manager reviews
• Track career development

Company Data

• Create new companies
• Access and update company information

Tax and Compliance

• Access tax payment and filing information
• Manage compliance-related data

Reporting and Analytics

• Generate customizable reports
• Access team insights and survey data

Authentication and Security

• Manage API tokens and OAuth2 authentication
• Handle company-level and organization-level access

It's important to note that the Gusto API uses OAuth2 for authentication and has specific endpoints for different levels of access (organization-level vs company-level). The API also supports pagination and has rate limits that developers need to be aware of when building integrations.