canonical: https://jentic.com/apis/gusto.com/gusto

# Gusto Embedded Payroll API

Embed full payroll processing, employee management, and contractor payments into partner applications through 24 endpoints. Handle company onboarding, bank account verification, payroll calculation and submission, employee lifecycle management, and contractor payment processing. Supports partner-managed company creation with migration readiness checks for transitioning existing Gusto customers.

## For AI agents

Run payroll calculations, submit payroll for processing, manage employees and contractors, and onboard new companies into an embedded payroll experience.

## Scope

Does not handle benefits marketplace enrollment, retirement plan administration, workers compensation insurance, or recruiting - use for payroll processing and employee pay management only.

## Capabilities

- Calculate payroll with earnings, deductions, and tax withholdings before submission
- Submit finalized payrolls for processing with direct deposit distribution
- Onboard partner-managed companies with bank account and tax setup
- Add and manage employees with compensation, benefits, and tax elections
- Process contractor payments with 1099 tracking and payment scheduling
- Verify migration readiness before transitioning existing Gusto companies to embedded

## Use cases

### AI Agent Payroll Processing

AI agents use the Gusto Embedded Payroll API through Jentic to automate pay runs without direct Gusto credentials. An agent searches for 'calculate and submit payroll', loads the schema for the calculate endpoint, reviews the totals, and then submits the payroll for processing. The two-step calculate-then-submit flow prevents accidental payroll submissions by requiring explicit confirmation.

Example prompt: Calculate payroll for company ID C001 for the current pay period, verify the total net pay amount, then submit the payroll for processing

### Embedded Payroll for SaaS Platforms

Partner applications embed Gusto's payroll engine to offer payroll as a native feature without building tax calculation, compliance, or direct deposit infrastructure. The partner-managed-companies endpoint handles company creation and setup, while payroll endpoints handle the ongoing run cycle. Partners earn revenue share while their customers get full-service payroll within the partner's UI.

Example prompt: Create a new partner-managed company with the business name, EIN, and primary contact email, then add a bank account for payroll funding

### Employee Lifecycle Management

Add, update, and offboard employees through the API with compensation details, tax elections, and benefits enrolment. The employees endpoint handles the full lifecycle from hire through termination, syncing with payroll calculations automatically. Changes to compensation or deductions reflect in the next payroll calculation without manual reconfiguration.

Example prompt: Add a new employee to company ID C001 with their name, start date, salary of $85,000, and filing status, then verify they appear in the next payroll calculation

### Contractor Payment Processing

Pay contractors and track 1099 obligations through dedicated contractor endpoints. The contractor-payments resource handles one-time and recurring payments with configurable payment methods. At year-end, payment history supports 1099-NEC generation for tax compliance without manual record aggregation.

Example prompt: Create a contractor payment of $5,000 for contractor ID CT001 at company ID C001 with payment date of next Friday

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /v1/partner-managed-companies | Create a partner-managed company |
| GET | /v1/companies/{company_id}/employees | List employees for a company |
| GET | /v1/companies/{company_id}/payrolls | List payrolls for a company |
| POST | /v1/companies/{company_id}/payrolls/{payroll_id}/calculate | Calculate payroll totals |
| POST | /v1/companies/{company_id}/payrolls/{payroll_id}/submit | Submit payroll for processing |
| GET | /v1/companies/{company_id}/contractors | List contractors for a company |
| POST | /v1/companies/{company_id}/contractor-payments | Create a contractor payment |
| GET | /v1/companies/{company_id}/bank-accounts | List company bank accounts |

## Key resources

- **Companies** — Company profiles, partner-managed company creation, and migration readiness
- **Employees** — Employee records with compensation, tax, and benefits data
- **Payrolls** — Payroll runs with calculate, review, and submit lifecycle
- **Contractors** — Contractor profiles and payment records with 1099 tracking
- **Bank Accounts** — Company bank accounts for payroll funding and direct deposit

## Why Jentic

- **Setup:** Wiring the Gusto Embedded Payroll API by hand means handling its bearer tokens against api.gusto.com, tracking company-scoped access, and coding the multi-step calculate-then-submit payroll flow plus retries yourself. Through Jentic you install once, import Gusto Embedded Payroll from the API Directory, store the credentials once, and your agent calls it.
- **Permission scoping:** Gusto puts the company id and payroll id in the URL path (/companies/{company_id}/payrolls/{payroll_id}/...), so a rule can pin your agent to one company: it can calculate and submit that company's payroll and nothing else. You choose the operations it may call, so contractor payments or partner-managed company creation are not included unless you add them.
- **Credential handling:** Your Gusto client credentials and bearer tokens are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run payroll for a company' or 'list a company's employees', and Jentic returns the matching Gusto operation with its input schema so the agent can call calculate then submit without navigating the partner documentation.

## Related APIs

- **ADP API** — Enterprise payroll and HR platform for large organisations with complex pay structures
- **Paylocity API** — Mid-market payroll and HCM platform with time tracking and talent management
- **BambooHR API** — HRIS platform for employee records, time-off, onboarding, and performance management
- **Rippling API** — Unified HR, IT, and payroll platform with device management and app provisioning

## FAQ

### What authentication does the Gusto Embedded Payroll API use?

The API uses OAuth 2.0 Bearer tokens obtained through the token endpoint at POST /v1/token. Partners authenticate with client credentials and receive access tokens scoped to specific companies. Through Jentic, OAuth tokens are managed in your Jentic One instance so agents receive scoped access without handling client secrets.

### Can I calculate payroll before submitting it for processing?

Yes. The two-step flow requires calling POST /v1/companies/{company_id}/payrolls/{payroll_id}/calculate first, which returns computed earnings, deductions, taxes, and net pay for review. Only after confirming the totals do you call POST /v1/companies/{company_id}/payrolls/{payroll_id}/submit to initiate direct deposits and tax payments.

### What are the rate limits for the Gusto Embedded Payroll API?

Gusto enforces rate limits per partner application, typically 100 requests per minute per company. The API returns HTTP 429 with rate limit headers when exceeded. For payroll operations, the calculate and submit endpoints have additional safeguards preventing duplicate submissions within the same pay period.

### How do I run payroll through Jentic?

Search Jentic for 'calculate and submit payroll', load the schema for the calculate endpoint at POST /v1/companies/{company_id}/payrolls/{payroll_id}/calculate, execute to get totals, then load and call the submit endpoint. Install with pip install jentic and authenticate through Jentic One, the self-hosted execution layer.

### Does the Gusto API support contractor payments?

Yes. POST /v1/companies/{company_id}/contractor-payments creates a payment for a specific contractor with the amount, payment date, and payment method. GET /v1/companies/{company_id}/contractors lists all contractors. Payments are tracked for 1099-NEC generation at year-end.

### Can I migrate an existing Gusto company to embedded payroll?

Yes. First check migration readiness via GET /v1/partner-managed-companies/{company_id}/migration_readiness, which returns blocking issues if any. Once ready, POST /v1/partner-managed-companies/{company_id}/migrate transfers the company to your partner-managed account while preserving their payroll history and employee data.

### Can I limit what my agent is allowed to do with the Gusto Embedded Payroll API?

Yes. Because you run Jentic One yourself, your own rules decide which Gusto operations and credentials your agent may use. Since Gusto puts the company id and payroll id in the URL path, you can pin the agent to a single company and allow only the operations you want, such as calculating and submitting that company's payroll while excluding contractor payments or partner-managed company creation. Your Gusto client credentials and bearer tokens stay in your Jentic One instance and are injected at execution time, so the agent never sees them.