Manage company forms

Gusto Embedded provides a structured system for managing company forms related to payroll, tax compliance, and onboarding. These forms are essential for ensuring companies meet regulatory requirements.

Company forms are categorized into three primary groups:

• Onboarding forms
• Payroll-related forms
• Tax forms

Learn how to sign these forms during company onboarding, or more about the types of company forms.

Sign company forms

Prerequisites

Before signing company forms to complete onboarding:

• A signatory must be designated: You can create a signatory using the POST companies/{company_uuid}/signatories endpoint. See the Onboard a company guide for more detailed instructions on creating a signatory.
• The following onboarding steps must be completed. See the Onboard a company guide for more information.
  • "add_employees"
  • "federal_tax_setup"
  • "state_setup"
  • "add_bank_info"
  • "payroll_schedule"

List all company forms

To see a list of all current company forms, use the GET companies/{company_uuid}/forms endpoint.

A new company will have to complete the Direct Deposit Authorization and Form 8655 at minimum, plus any state-specific authorization forms.

Sample request

curl --request GET \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/forms \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<COMPANY_ACCESS_TOKEN>>'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/companies/{company_uuid}/forms';
const options = {
  method: 'GET',
  headers: {accept: 'application/json', authorization: 'Bearer <<COMPANY_ACCESS_TOKEN>>'}
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

Sample response

The response will be an array of form objects. Look for forms where "requires_signing": true.

[
  {
    "uuid": "48cdd5ec-a4dd-4840-a424-ad79f38d8408",
    "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
  }
]

Sign required forms

If a form has requires_signing = true, use the PUT forms/{form_uuid}/sign endpoint.

curl --request PUT \
     --url https://api.gusto-demo.com/v1/forms/{form_uuid}/sign \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<COMPANY_ACCESS_TOKEN>>' \
     --header 'content-type: application/json' \
     --data '
{
     "signature_text": "Jean Valjean",
     "agree": true,
     "signed_by_ip_address": "192.168.0.1"
}
'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/forms/{form_uuid}/sign';
const options = {
  method: 'PUT',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <<COMPANY_ACCESS_TOKEN>>'
  },
  body: JSON.stringify({
    signature_text: 'Jean Valjean',
    agree: true,
    signed_by_ip_address: '192.168.0.1'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

Retrieve PDFs of forms

You can retrieve any form as a PDF in order to supply it to your users. To get a PDF use the uuid for the specific form and the GET /v1/forms/{form_uuid}/pdf endpoint.

Sample request

curl --request GET \
     --url https://api.gusto-demo.com/v1/forms/{form_uuid}/pdf \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<COMPANY_ACCESS_TOKEN>>'

const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/forms/{form_uuid}/pdf';
const options = {
  method: 'GET',
  headers: {accept: 'application/json', authorization: 'Bearer <<COMPANY_ACCESS_TOKEN>>'}
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

Sample response

{
  "uuid": "48cdd5ec-a4dd-4840-a424-ad79f38d8408",
  "document_url": "https://app.gusto-demo.com/assets/forms/7757842065202782/original/company_direct_deposit20211007-48226-gsqo8k.pdf?1633667020",
  "document_content_type": "application/pdf"
}

📘

PDF link expiration

For security, links to form PDFs expire within 30 seconds. We recommend that you download and store the form securely in your application to prevent link expiration.

Types of company forms

Onboarding forms

Onboarding forms are required to properly set up a company in the payroll system.

These essential documents include:

• Form 8655 (Reporting Agent Authorization)
• Direct Deposit Authorization

Depending on the company's work locations, some states may mandate additional authorization forms.

Payroll-related forms

Payroll-related forms are documents used for continuous payroll management and reporting.

This category includes items such as:

• Quarterly tax returns
• Annual payroll summaries
• Wage statements like W-2s and 1099s

Tax forms

Company tax forms will only become available when payrolls have been processed and the associated tax filings have been generated. The tax forms will then be accessible in accordance with the filing frequency requirements of each agency. For a list of all state and federal tax forms filed by Gusto, please refer to this support article.

This group includes federal and state documents such as:

• Form 941 (Employer's Quarterly Federal Tax Return)
• Form 944 (Employer's Annual Federal Tax Return)
• Form 940 (Employer's Annual Federal Unemployment (FUTA) Tax Return)

The required state-specific tax filings can vary based on where employees are working from.