canonical: https://jentic.com/apis/gusto-demo.com/gusto-embedded-payroll

# Gusto Demo Gusto Embedded Payroll API

Jentic publishes the only available OpenAPI specification for Gusto Embedded Payroll API, keeping it validated and agent-ready. Gusto Embedded Payroll is the white-label payroll platform partners use to run US payroll inside their own product. Its 213 endpoints cover partner-managed company creation and migration, federal and state tax details, employees and contractors, jobs and compensations, payroll runs, off-cycle and historical payrolls, garnishments, time-off policies, holiday pay, employee benefits, signatories, and onboarding flows. Authentication uses partner-scoped tokens via Authorization bearer or API key header.

## For AI agents

Run embedded US payroll for partner-managed companies - create companies, manage employees and contractors, configure tax details, and execute payroll runs.

## Scope

Does not handle international payroll, expense reimbursement workflows, or applicant tracking - use for US embedded payroll, employee management, and tax filing through Gusto Embedded only.

## Capabilities

- Create and migrate partner-managed companies including federal and state tax detail setup
- Manage employee and contractor records with addresses, jobs, and compensation history
- Run regular payroll, off-cycle payrolls, and post historical payroll data
- Configure pay schedules, time-off policies, and holiday pay rules per company
- Set up garnishments and post-tax deductions on employee records
- Drive onboarding flows including terms-of-service acceptance and signatory assignment
- Read invoicing data and process refresh-token requests for partner authentication

## Use cases

### Embedded payroll inside a vertical SaaS

A vertical SaaS - for example construction, restaurants, or healthcare scheduling - embeds Gusto payroll directly so its customers run payroll without leaving the product. Partner-managed company creation, tax-detail configuration, and payroll-run endpoints power the end-to-end flow from sign-up through monthly pay cycles. Embedded launches typically take six to twelve weeks once partner credentials are issued.

Example prompt: Call POST `/v1/partner_managed_companies` to create a company, then POST tax details under `/v1/companies/{company_id}/federal_tax_details` before the first payroll.

### Historical payroll migration onto Gusto Embedded

When a customer moves to a partner's embedded payroll, prior-period payroll history must be loaded so year-to-date tax calculations and W-2 generation are accurate. The historical payroll endpoints accept prior pay periods and gross-to-net amounts so Gusto can replay year-to-date balances cleanly without manual reconciliation.

Example prompt: POST historical payroll records for the current year against `/v1/partner_managed_companies/{company_uuid}/migrate` and verify YTD totals match the source system.

### Off-cycle and bonus payroll runs

Partner products trigger off-cycle bonus or correction runs outside the regular pay schedule. The off-cycle payroll endpoints let the partner specify employees, gross amounts, and tax treatment for a single dated run, and produce the matching pay stubs and tax filings.

Example prompt: Create an off-cycle payroll for a list of employees with a specified bonus amount and confirm the run reaches the calculated state.

### AI agent payroll ops via Jentic

An AI assistant in a partner's admin console handles a request to add an employee to a partner-managed company, set their job and compensation, and assign them to the next payroll run. Through Jentic the agent loads the right Embedded Payroll endpoints on demand, with token refresh handled automatically.

Example prompt: Search Jentic for 'add an employee to gusto embedded', load the matching operation, and execute with the company UUID, employee details, and starting compensation.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/partner_managed_companies` | Create a partner-managed company |
| GET | `/v1/companies/{company_id}` | Get a company |
| PUT | `/v1/partner_managed_companies/{company_uuid}/migrate` | Migrate company to embedded payroll |
| GET | `/v1/companies/{company_id}/federal_tax_details` | Get federal tax details |
| PUT | `/v1/companies/{company_id}/federal_tax_details` | Update federal tax details |
| POST | `/oauth/token` | Refresh access token |

## Key resources

- **Partner Managed Companies** — Create, migrate, and manage companies under a partner's account
- **Employees** — Manage employees, addresses, employments, jobs, and compensations
- **Contractors** — Manage 1099 contractors alongside W-2 employees
- **Payrolls** — Run regular, off-cycle, and historical payrolls
- **Federal Tax Details** — Configure federal tax setup for each company
- **Pay Schedules** — Define pay frequencies and pay-date logic per company
- **Company Benefits** — Configure benefit plans available to a company
- **Webhooks** — Subscribe to payroll, employee, and tax events

## Why Jentic

- **Setup:** Wiring the Gusto Embedded Payroll API by hand means handling partner-scoped tokens, refreshing them before expiry, choosing the demo or production host, and coding required scopes across a large payroll surface 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 Embedded Payroll puts the company id in the URL path (`/companies/{company_id}/...`), so a rule can pin your agent to one company: it can read and update that company's federal tax details and nothing else. You choose the operations it may call, so creating partner-managed companies or running a migration is not included unless you add it.
- **Credential handling:** Your partner-scoped Gusto Embedded tokens are stored once, encrypted, by your own Jentic One instance and injected at execution time, with refresh handled automatically before expiry. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'run Gusto embedded payroll' or 'read a company's federal tax details', and Jentic returns the matching operation with its input schema and required scope so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Rippling** — Combined HR, IT, and payroll platform with partner APIs
- **ADP** — Enterprise payroll provider with broad market coverage
- **Deputy** — Time-tracking and shift-scheduling that feeds hours into payroll

## FAQ

### Why is there no official OpenAPI spec for Gusto Embedded Payroll API?

Gusto does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Gusto Embedded Payroll API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

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

Embedded Payroll uses partner-scoped tokens - an Authorization bearer token plus an X-Gusto-API-Version header, with API-key flows available for some operations. Tokens are refreshed via POST `/oauth/token.` Through Jentic the partner credential is held in the vault and refreshed automatically.

### Can I create a new company under my partner account with the Gusto Embedded Payroll API?

Yes. POST `/v1/partner_managed_companies` creates a partner-managed company, returns its UUID, and lets you continue with federal tax details, locations, and employee setup. Use the migrate endpoint when bringing an existing company over.

### Can I run an off-cycle payroll with the Gusto Embedded Payroll API?

Yes. The payrolls resource includes off-cycle endpoints that accept a list of employees, gross amounts, and a check date. Submit, calculate, and approve the run through the standard payroll lifecycle endpoints.

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

Embedded Payroll enforces partner-tier rate limits scoped to each partner credential, typically a few requests per second per token. Pace high-volume migration calls and respect Retry-After on 429 responses; subscribe to webhooks instead of polling for payroll-state changes.

### How do I update federal tax details for a Gusto Embedded company through Jentic?

Search Jentic for 'update gusto federal tax details', load the PUT `/v1/companies/{company_id}/federal_tax_details` operation, then execute with the company ID and tax detail payload. Install with pip install jentic.

### 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 operations and credentials the agent may use. Gusto Embedded Payroll puts the company id in the URL path (`/companies/{company_id}/...`), so you can pin the agent to a single company and let it read and update only that company's federal tax details. Since you pick the operations it may call, actions like creating partner-managed companies or running a migration stay off-limits unless you explicitly allow them.