W-2 employee forms

There are a variety of employee forms that are required during different stages of employment. All forms that are supported via the API can be retrieved using the GET /v1/employees/{employee_uuid}/forms.

Form types

Onboarding

All Onboarding forms must be signed before an employee is paid using the PUT /v1/forms/{form_uuid}/sign endpoint. The following table provides an overview of the core forms required during onboarding, detailing each form's purpose and whether the Gusto API supports it.

Document	Description	API Support
Federal W-4	W-4 Employee Withholding Allowance: This document records the employee's federal tax withholding allowance.	Yes
State W-4	This document records the employee's state tax withholding allowance.	No
Direct Deposit Authorization	This document authorizes Gusto to initiate debits and credits from a bank account in order to pay people. If `payment_method` = `Direct Deposit`, requires a signature.	Yes
I-9	This document records a person's authorization to work in the USA.	Yes
New Hire Report	This document reports new hires to the state where someone is employed (for example in California this is form DE-34)	Yes

Ongoing

Employers can also collect details about employee paystubs using the GET /v1/payrolls/{payroll_uuid}/employees/{employee_uuid}/pay_stub endpoint. The following table outlines the paystub document retrieved via the API, including its components and support status.

Document	Description	API Support
Paystubs	Each paystub includes gross earnings, employee and employer taxes, employee benefits and deductions, employer contributions, time off taken and accrued, reimbursements, and your check amount. The taxes on your paystub may vary if your gross pay changes paycheck to paycheck. Your net pay is the remaining amount of gross pay after taxes, benefits, and any deductions are made. Due to PII and PHI you must deliver paystubs through a secure method.	Yes

End of year

At year-end, employers must provide employees with annual tax documents. The table below lists the year-end forms available via the API, their descriptions, and their support status.

Document	Description	API Support
W-2	This document reports annual wages, taxes, deductions, and other salary information. The information on your W-2 is needed when preparing your federal income tax return—Forms W-2 are available in mid-January for the previous calendar year.	Yes
W-2-C	An amended version of the W-2, should any changes occur after the original W-2 is issued.	Yes

Retrieve forms

You can retrieve all supported forms via the API using the GET /v1/employees/{employee_uuid}/forms endpoint.

Sample request

curl --request GET \
     --url https://api.gusto-demo.com/v1/employees/{EMPLOYEE_UUID}/forms \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer COMPANY_API_TOKEN'

Sample response

[
  {
    "uuid": "FORM_UUID",
    "name": "company_direct_deposit",
    "title": "Direct Deposit Authorization",
    "description": "We need you to sign paperwork to authorize us to debit and credit your bank account and file and pay your taxes.",
    "draft": false,
    "quarter": null,
    "year": null,
    "document_content_type": "application/pdf",
    "requires_signing": true
  }
]

Retrieve a form in PDF

You can also retrieve the PDF file of the form. Use the GET /v1/forms/{form_id}/pdf endpoint to retrieve a company form in PDF:

Sample request

curl --request GET \
     --url https://api.gusto-demo.com/v1/forms/{FORM_UUID}/pdf \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer COMPANY_API_TOKEN'

Sample response

{
  "uuid": "FORM_UUID",
  "document_url": "https://app.gusto-demo.com/assets/forms/7757842065202782/original/company_direct_deposit20211007-48226-gsqo8k.pdf?1633667020",
  "document_content_type": "application/pdf"
}

Sign an onboarding form

Use the PUT /v1/forms/{form_uuid}/sign endpoint to sign an onboarding form:

Sample request

curl --request PUT \
     --url https://api.gusto-demo.com/v1/forms/{FORM_UUID}/sign \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer COMPANY_API_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
  "agree": true,
  "signature_text": "Jane Smith",
  "signed_by_ip_address": "192.168.0.1"
}
'

Sample response

{
  "uuid": "FORM_UUID",
  "name": "company_direct_deposit",
  "title": "Direct Deposit Authorization",
  "description": "We need you to sign paperwork to authorize us to debit and credit your bank account and file and pay your taxes.",
  "draft": false,
  "quarter": null,
  "year": null,
  "document_content_type": "application/pdf",
  "requires_signing": true
}

Retrieve an employee’s pay stub

Use the GET /v1/payrolls/{payroll_uuid}/employees/{employee_uuid}/pay_stub endpoint to retrieve an employee’s paystub, for a specific payroll, as application/pdf:

Sample request

curl --request GET \
     --url https://api.gusto-demo.com/v1/payrolls/{PAYROLL_UUID}/employees/{EMPLOYEE_UUID}/pay_stub \
     --header 'X-Gusto-API-Version: 2024-04-01' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer COMPANY_API_TOKEN'