Configure company tax information

As part of onboarding, companies must configure two types of tax information to ensure payroll is filed and paid correctly:

Federal tax: Collected by the U.S. federal government based on employee wages. Companies are responsible for withholding the correct amounts and remitting them on schedule.
State tax: Collected by the state where employees work or live. Not all states require income tax, but for those that do, companies must register and set up withholding accounts.

Setting up federal and state tax details at the company level is a prerequisite for running payroll and ensuring compliance with filing obligations.

Federal taxes

A company must set up federal tax information to ensure accurate filing.

1. Get a company's federal tax version

To provide federal tax details, you will first need to get the version of the tax details using the GET /v1/companies/{company_id}/federal_tax_details endpoint.

Sample request

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

Sample response

{
  "version": "5521489cc7c93732300805dcf87a5fd3",
  "tax_payer_type": "S-Corporation",
  "taxable_as_scorp": true,
  "filing_form": "941",
  "has_ein": true,
  "ein_verified": true,
  "ein_verification": {
    "status": "verified"
  },
  "legal_name": "Company Name LLC",
  "effective_date": "2024-01-01",
  "deposit_schedule": "Semiweekly"
}

2. Update a company’s federal tax details

Once you have the version you can update the federal tax details using the PUT /v1/companies/{company_id}/federal_tax_details endpoint.

Sample request

curl --request PUT \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/federal_tax_details \
     --header 'accept: application/json' \
     --header 'authorization: Bearer {{company_access_token}}' \
     --header 'content-type: application/json' \
     --data '
{
     "version": "6cb95e00540706ca48d4577b3c839fbe",
     "tax_payer_type": "LLP",
     "taxable_as_scorp": false,
     "filing_form": "944",
     "has_ein": true,
     "ein_verified": false,
     "legal_name": "Mushnik\'s Flower Shop Inc"
}'

Sample response

{
  "version": "6cb95e00540706ca48d4577b3c839fbe",
  "tax_payer_type": "LLP",
  "taxable_as_scorp": false,
  "filing_form": "941",
  "has_ein": true,
  "ein_verified": false,
  "ein_verification": {
    "status": "pending"
  },
  "legal_name": "Mushnik\'s Flower Shop Inc",
  "effective_date": "2023-09-12",
  "deposit_schedule": "Semiweekly"
}

State taxes

State tax setup depends on the company’s registered location and the home and work locations of its employees. Companies must register with the appropriate state tax agencies in each state where they have tax obligations.

(Recommended) Use state setup flow

Due to the complexity of state tax setup, we strongly recommend using the state_setup flow rather than manually calling the API endpoints.

Manual API steps

1. Get the company’s state taxes

The GET /v1/companies/{company_uuid}/tax_requirements/{state} endpoint provides the needed information for a company’s state taxes. state is the 2-letter abbreviation of the US state.

Sample request

curl --request GET \
     --url https://api.gusto-demo.com/v1/companies/{company_id}/tax_requirements/GA \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json'

Sample response

{
  "company_uuid": "6c14eac3-0da2-474d-bda1-786b3602d381",
  "state": "GA",
  "requirement_sets": [
    {
      "state": "GA",
      "key": "registrations",
      "label": "Registrations",
      "effective_from": null,
      "requirements": [
        {
          "key": "71653ec0-00b5-4c66-a58b-22ecf21704c5",
          "applicable_if": [],
          "label": "Withholding Number",
          "description": "If you have run payroll in the past in GA, find your withholding number on notices received from the Georgia Department of Revenue, or call the agency at (877) 423-6711. If you don’t have a number yet, you should <a target='_blank' data-bypass href='https://gtc.dor.ga.gov/_/#1'>register the business online</a>. The last two characters of your ID must be upper case letters.",
          "value": "1233214-AB",
          "metadata": {
            "type": "text"
          }
        },
        {
          "key": "6c0911ab-5860-412e-bdef-6437cd881df5",
          "applicable_if": [],
          "label": "DOL Account Number",
          "description": "If you have run payroll in the past in GA, find your DOL account number on notices received from the Georgia Department of Labor, or call the agency at (404) 232-3300. If you don’t have an account number yet, please <a target='_blank' data-bypass href='https://support.gusto.com/hc/en-us/articles/210139038#registerdol'>follow the instructions here</a> to register your business with the Georgia Dept. of Labor.",
          "value": "474747-88",
          "metadata": {
            "type": "text"
          }
        }
      ]
    },
    {
      "state": "GA",
      "key": "taxrates",
      "label": "Tax Rates",
      "effective_from": "2022-01-01",
      "requirements": [
        {
          "key": "e0ac2284-8d30-4100-ae23-f85f9574868b",
          "applicable_if": [],
          "label": "Total Tax Rate",
          "description": "Haven't received your assigned rate yet? <a target='_blank' data-bypass href='https://support.gusto.com/article/106622236100000/State-unemployment-insurance-(SUI)-tax'>Find the new employer rate</a> and enter it here.",
          "value": "0.05",
          "metadata": {
            "type": "tax_rate",
            "validation": {
              "type": "min_max",
              "min": "0.0004",
              "max": "0.081"
            }
          }
        }
      ]
    },
    {
      "state": "GA",
      "key": "depositschedules",
      "label": "Deposit Schedules",
      "effective_from": "2022-01-01",
      "requirements": [
        {
          "key": "6ddfcbeb-94d3-4003-bfc2-8c6e1ca9f70c",
          "applicable_if": [],
          "label": "Deposit Schedule",
          "description": "Georgia rejects payments made on the wrong schedule. GA employers receive their schedule on a registration verification letter after registering with the Georgia Dept. of Revenue. If you are unsure, call the agency at (877) 423-6711. If you did not register your business yet, please <a target='_blank' data-bypass href='https://gtc.dor.ga.gov/_/#2'>register the business with the Georgia Dept. of Revenue</a>.",
          "value": "Semi-weekly",
          "metadata": {
            "type": "select",
            "options": [
              {
                "label": "Semiweekly",
                "value": "Semi-weekly"
              },
              {
                "label": "Monthly",
                "value": "Monthly"
              },
              {
                "label": "Quarterly",
                "value": "Quarterly"
              }
            ]
          }
        }
      ]
    }
  ]
}

2. Update the company’s state taxes

Given the information that needs to be added or updated, call the PUT companies/{company_uuid}/tax_requirements/{state} endpoint.

Sample request

curl --request PUT \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/tax_requirements/{state} \
     --header 'X-Gusto-API-Version: 2025-06-15' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "requirement_sets": [
    {
      "key": "registrations",
      "state": "GA",
      "requirements": [
        {
          "key": "71653ec0-00b5-4c66-a58b-22ecf21704c5",
          "value": "1233214-AB"
        }
      ],
      "effective_from": "2025-10-03"
    }
  ]
}
'

Sample response

The response will return 200 - OK

OK