These docs are for v2023-09-01. Click to read the latest docs for v2024-04-01.

Send Company Information

📘

The bearer token should be specified via the Authorization HTTP header for these requests.

After creating the company you can now pass any company information that you already collect using our API. If you do not already collect this information, you can build a UI in your application so the user can enter this information to pass along to Gusto. This information will pre-populate fields in Gusto's co-branded Onboarding Flows so the payroll administrator will not need to provide this information twice.

Using the company_uuid from the response of the partner managed company endpoint, you can make the following API calls to create and update company information:

Create a Company Location

Gusto requires the company’s mailing and filing address and all addresses where the company has employees physically working in the United States. This includes remote employees and employees who work from home. Set these addresses using the create a company location endpoint. You can specify if the address you are creating is the mailing_address or filing_address in your request ie. “mailing_address”: “true”

❗️

Prerequisites

A company location must be created before a job for an employee can be created since location_id is a required field to create a job.

Update Federal Tax Details

The update Federal Tax Details endpoint is used to update attributes relevant for a company’s federal taxes. Gusto requires the company's federal tax details in order to file and pay taxes correctly. You can find this info on the company's IRS Form CP-575. You will need to provide the company’s legal_name, ein, tax_payer_type, filing_form (941 or 944), and whether this company should be taxable_as_scorp.

Allowed tax_payer_type values:

  • C-Corporation
  • S-Corporation
  • Sole proprietor
  • LLC
  • LLP
  • Limited partnership
  • Co-ownership
  • Association
  • Trusteeship
  • General partnership
  • Joint venture
  • Non-Profit

Update a Company Industry Selection

The update a company industry selection endpoint is used to update the company’s industry selection using naics_code and sic_codes. Gusto requires this information to stay compliance with finance regulations. North American Industry Classification System (NAICS) is used to classify businesses with a six digit number based on the primary type of work the business performs. SIC codes are the list of Standard Industrial Classification, which are four digit numbers that categorize the industries that companies belong to based on their business activities. You can look up a company’s NAICS and SIC codes here.

Create a Company Bank Account

The create a company bank account endpoint creates a new company bank account. If a default bank account exists, the new bank account will replace it as the company's default funding method. Required fields to make this request include routing_number, account_number, and account_type (Checking, Savings).

Upon being created, two verification deposits are automatically sent to the bank account in 1-2 business days, and the bank account's verification_status is awaiting_deposits.

When the deposits are successfully transferred, the verification_status changes to ready_for_verification, at which point the verify endpoint can be used to verify the bank account. After successful verification, the bank account's verification_status is verified.

📘

Demo Environment

Our API validates the routing number to ensure it's a valid US routing number and will reject false inputs. When testing in Gusto's demo environment, you can use this sample routing number: 102001017

Create a New Single Pay Schedule

The create a new single pay schedule endpoint creates one pay schedule during company onboarding and cannot be used if the company has processed a payroll. Creating multiple pay schedules at this time is not supported. To change a pay schedule, the end user will need to login to Gusto to edit their pay schedule. Be sure to check state laws to know what schedule is right for your customers.
When setting a pay schedule, the following information is needed:

  • frequency (string) - The frequency that employees on this pay schedule are paid with Gusto. Allowed values: Every week Every other week Twice per month Monthly
  • anchor_pay_date (string) - the first date that employees on this pay schedule are paid with Gusto
  • anchor_end_of_pay_period (string) - The last date of the first pay period. This can be the same date as the anchor pay date, but doesn't have to be.
  • day_1 and day_2: (integer between 1 and 31 or null) Indicates the first day of the month that employees are paid. This field is only relevant for pay schedules with the Twice per month and Monthly frequencies. It will be null for pay schedules with other frequencies.

When you select the anchor_end_of_pay_period, our system will calculate that together with the frequency to determine the pay periods on this schedule.

Create a Signatory

Gusto requires a signatory to sign key company forms for payroll. The create a signatory endpoint creates a company signatory who can legally sign forms. The company signatory is someone, usually an executive, designated to sign agreements on the company's behalf.

Please note that there can only be a single primary signatory in a company.

Verify a Company Bank Account

After creating the company bank account, Gusto will automatically issue two verification deposits to the bank account, and the bank account's verification_status will be awaiting_deposits. This can take 1-2 business days. When the deposits are successfully transferred, the verification_status changes to ready_for_verification, at which point the verify a company bank account endpoint can be used to verify the bank account. After successful verification, the bank account's verification_status is verified.

The order of the two deposits specified in request parameters does not matter. There's a maximum of 5 verification attempts, after which we will automatically initiate a new set of micro-deposits and require the bank account to be verified with the new micro-deposits.

📘

Demo Environment

Due to the nature in which our demo environment behaves, there is a separate endpoint for verifying the company bank account in demo.

We provide the endpoint POST /v1/companies/{company_id_or_uuid}/bank_accounts/{bank_account_uuid}/send_test_deposits to facilitate bank account verification in the demo environment. This endpoint simulates the micro-deposits transfer and returns them in the response. You can call this endpoint as many times as you wish to retrieve the values of the two micro deposits.