---
title: "Create an external payroll for a company"
method: POST
path: "/v1/companies/{company_uuid}/external_payrolls"
tags: ["External Payrolls"]
---

# Create an external payroll for a company

`POST /v1/companies/{company_uuid}/external_payrolls`

Creates a new external payroll for a company.

scope: `external_payrolls:write`

## Path parameters

- `company_uuid` string, required

## Headers

- `X-Gusto-API-Version` '2026-06-15'

## Request body

- ExternalPayrollCreateRequest — The request body for creating an external payroll.
  - `check_date` string, date, required — The check date of the external payroll.
  - `payment_period_start_date` string, date, required — The start date of the external payroll payment period.
  - `payment_period_end_date` string, date, required — The end date of the external payroll payment period.

## Response `200`

Success

- ExternalPayroll — The representation of an external payroll.
  - `uuid` string, required — The UUID of the external payroll.
  - `company_uuid` string — The UUID of the company.
  - `check_date` string — External payroll's check date.
  - `payment_period_start_date` string — External payroll's pay period start date.
  - `payment_period_end_date` string — External payroll's pay period end date.
  - `status` 'unprocessed' | 'processed' — The status of the external payroll. The status will be `unprocessed` when the external payroll is created and transition to `processed` once tax liabilities are entered and finalized. Once in the `processed` status all actions that can edit an external payroll will be disabled.
  - `external_payroll_items` object[] — External payroll items for employees
    - `employee_uuid` string
    - `earnings` object[]
      - `amount` string, float
      - `hours` string, float
      - `earning_type` string
      - `earning_id` integer
    - `benefits` object[]
      - `benefit_id` integer
      - `company_contribution_amount` string, float
      - `employee_deduction_amount` string, float
    - `taxes` object[]
      - `tax_id` integer
      - `amount` string, float
  - `applicable_earnings` object[] — Applicable earnings based on company provisioning.
    - `earning_type` string
    - `earning_id` number
    - `name` string
    - `input_type` string
    - `category` string
  - `applicable_benefits` object[], nullable — Applicable benefits based on company provisioning.
    - `id` integer
    - `description` string
    - `active` boolean
  - `applicable_taxes` object[] — Applicable taxes based on company provisioning.
    - `id` integer
    - `name` string
    - `employer_tax` boolean — Some taxes may have an amount withheld from the employee and an amount withheld from the employer, e.g. Social Security. A `true` value indicates this is the employer's amount.
    - `resident_tax` boolean — Some taxes may have different rates or reporting requirements depending on if the employee is a resident or non-resident of the tax jurisdiction.
  - `metadata` object — Stores metadata of the external payroll.
    - `deletable` boolean — Determines if the external payroll can be deleted.

## Other responses

- `404` — Not Found The requested resource does not exist. Make sure the provided UUID is valid.
- `422` — Unprocessable Entity This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.

---

[API](https://skmtc.net/gusto/apis/gusto-api.md) · [All operations](https://skmtc.net/gusto/apis/gusto-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gusto/gusto-api/revisions/826dfa57fb3b/schema)