Payroll systems · Gusto

Gusto Embedded Payroll

Gusto's own documentation covers employees, pay statements, deduction write, bank account write, tax forms, hours and webhooks through the API. Access: Self-serve demo; partner for prod.

Integration method grade A · field-level docs publicly readable · last verified 2026-09-10 · Gusto Embedded Payroll — benefits reference

What the API lets you do

Question	Answer	Conf	What the documentation says
How do you get API access?	Self-serve demo; partner for prod	D	Demo keys are self-serve; production requires commercial, security and implementation reviews with Gusto's partnerships team. Source
Can you read employees and pay rates?	Yes — employees, jobs, pay	D	GET /v1/jobs/{job_id}/compensations returns rate, payment_unit, flsa_status and effective_date. Source
Can you read pay statements?	Yes — payrolls + pay stubs	D	GET payroll returns employee_compensations with taxes and deductions; GET /v1/employees/{id}/pay_stubs returns summaries. Source
Can you write a deduction?	Yes — benefits, garnishments	D	POST employee garnishments (fixed or percentage) and POST /v1/employees/{id}/employee_benefits. Source
Can you write a direct deposit account?	Yes — bank accounts	D	POST /v1/employees/{employee_id}/bank_accounts with routing and account numbers; also updates the payment method. Source
Can you read W-2s?	Yes — W-2 via employee forms	D	GET /v1/employees/{employee_id}/forms lists forms including US_W-2, mostly as PDF. Source
Can you read hours worked?	Hours via payroll only	D	Regular and overtime hours come from hourly_compensations on a payroll; timesheet endpoints sit in Gusto's separate App Integrations API. Source
Does it push change events?	Yes — subscriptions	D	API-created subscriptions with events such as payroll.paid; HMAC-SHA256 signed; 16 retries over 3 days. Source
How does an integration authenticate?	OAuth 2.0	D	System access tokens for partner-level calls and authorisation-code flow with refresh tokens per company; tokens expire in two hours. Source

Deduction write, in detail

For benefits, HSA/FSA and 401(k) integrations. 3 of 10 fields are unverified — no public source states the answer. Compare every system on the deduction write detail page.

Field	Value	Conf	Note — and what a correct answer needed
Deduction read	Yes — API	D	GET employee benefits, company benefits, and the supported benefit type list.
Deduction write	API	D	POST / PUT / DELETE on employee benefits and company benefits — but gated per benefit type by writable_by_application.
Pre-tax vs post-tax at write	Explicit	D	The clearest model assessed. Each benefit type carries pretax, posttax and imputed booleans, plus healthcare, retirement and yearly_limit flags. deduction_reduces_taxable_income is settable but documented as controlling Group Term Life only.
Amount vs percent	Both — explicit, both sides	D	employee_deduction with deduct_as_percentage boolean; employer side is a contribution object with type and value supporting amount, percentage or tiered. Capped by employee_deduction_annual_maximum and company_contribution_annual_maximum, where null means no limit.
Effective dating	Yes — effective_date / expiration_date	D	Plain dates on the employee benefit. No distinction between a reporting effective date and the first affected pay date, unlike Paylocity.
Retro adjustment	Unverified	U	Absent from the API reference. Correcting a past benefit amount appears only as a help-centre support workflow, which implies it is not an API operation — but the API docs never say so.
Employer contribution	First-class object	D	contribution {type, value}, elective boolean marking a matching contribution, company_contribution_annual_maximum, and catch_up documented as applying only to 401k and Roth 401k for employees over 50.
Code taxonomy shape	Vendor-fixed taxonomy	D	Not company-defined. Numeric benefit_type identifiers (1 Medical, 5 401(k), 111 529 College Savings). Each type carries writable_by_application, so read access to the taxonomy does not imply write access to it.
Auth model	Unverified	U	Not assessed.
Data freshness	Unverified	U	Not stated in the benefits reference.

D vendor-documented · U unverified · — not offered. See every payroll system side by side in the Payroll API Capability Matrix.