---
title: "Create a people batch"
method: POST
path: "/v1/companies/{company_id}/people_batches"
tags: ["People Batches"]
---

# Create a people batch

`POST /v1/companies/{company_id}/people_batches`

Creates a batch for bulk employee creation.

The batch is processed asynchronously. Use the returned batch UUID to poll for status and results.

scope: `people_batches:write`

## Path parameters

- `company_id` string, required

## Headers

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

## Request body

- object
  - `idempotency_key` string, uuid, required — A unique identifier to ensure idempotency of the batch request
  - `batch_action` 'create', required — The action to perform on the batch
  - `batch` object[], required — Array of people to create
    - `entity_type` 'employee', required — The type of entity to create
    - `person` object, required
      - `external_id` string, required — External identifier for the person
      - `first_name` string, required — Legal first name
      - `last_name` string, required — Legal last name
      - `middle_initial` string, nullable — Middle initial
      - `preferred_first_name` string, nullable — Preferred first name
      - `email` string, email, nullable — Personal email address
      - `work_email` string, email, nullable — Work email address
      - `ssn` string, nullable — Social Security Number (format: xxx-xx-xxxx)
      - `date_of_birth` string, date, nullable — Date of birth (YYYY-MM-DD)
      - `self_onboarding` boolean, nullable — Whether the employee will complete their own onboarding
    - `home_address` object — Home address for the employee
      - `street_1` string, required — Street address line 1
      - `street_2` string — Street address line 2
      - `city` string, required — City
      - `state` string, required — State abbreviation
      - `zip` string, required — ZIP code
      - `country` string — Country (defaults to USA)
      - `work_from_home` boolean — If true, a company work address will be created based on this home address and the `work_address` property is not allowed.
    - `work_address` object — Specify the company work location for the employee
      - `location_uuid` string, uuid, required — UUID of an existing company work location
    - `job` object — Job details for the employee (required if compensation is provided)
      - `title` string, required — Job title
      - `hire_date` string, date, required — The date when the employee was hired or rehired for the job.
      - `two_percent_shareholder` boolean — Whether the employee owns at least 2% of the company. Can only be `true` for S-Corp companies.
      - `state_wc_covered` boolean, nullable — Whether this job is eligible for workers' compensation coverage in the state of Washington (WA).
      - `state_wc_class_code` string, nullable — The risk class code for workers' compensation in Washington state. Please visit [Washington state's Risk Class page](https://www.lni.wa.gov/insurance/rates-risk-classes/risk-classes-for-workers-compensation/risk-class-lookup#/) to learn more.
    - `department` object — Department details for the employee
      - `department_uuid` string, uuid, required — UUID of an existing company department
    - `compensation` object — Compensation details for the employee (requires job to be provided)
      - `rate` string, required — The dollar amount paid per payment unit.
      - `payment_unit` 'Hour' | 'Week' | 'Month' | 'Year' | 'Paycheck', required — The unit accompanying the compensation rate. If the employee is an owner, rate should be `Paycheck`.
      - `flsa_status` 'Exempt' | 'Salaried Nonexempt' | 'Nonexempt' | 'Owner' | 'Commission Only Exempt' | 'Commission Only Nonexempt', required — The FLSA status for this compensation. Salaried ('Exempt') employees are paid a fixed salary every pay period. Salaried with overtime ('Salaried Nonexempt') employees are paid a fixed salary every pay period, and receive overtime pay when applicable. Hourly ( 'Nonexempt') employees are paid for the hours they work, and receive overtime pay when applicable. Commissioned employees ('Commission Only Exempt') earn wages based only on commission. Commissioned with overtime ('Commission Only Nonexempt') earn wages based on commission, and receive overtime pay when applicable. Owners ('Owner') are employees that own at least twenty percent of the company. If selecting `Owner`, `payment_unit` must be `"Paycheck"`.
    - `bank_accounts` object[] — Creates employee bank account(s) and payment method(s) for direct deposit. Payments can be split across accounts by Percentage or by Amount. If splitting payments by `Percentage`, all splits must have a `split_amount` and the percentages must add up to `100`. If splitting payments by `Amount`, the priority is set based on the order of the bank accounts in the array and the last bank account is the remainder account (should have `split_amount` set to `null`).
      - `name` string, nullable — Account nickname
      - `account_type` 'Checking' | 'Savings', required — Type of bank account
      - `routing_number` string, required — Bank routing number
      - `account_number` string, required — Bank account number
      - `type` 'Direct Deposit', required — Payment type (must be Direct Deposit)
      - `split_by` 'Amount' | 'Percentage', required — How to split deposits, must be the same for all bank accounts. If split_by is `Percentage`, then the split_amounts must add up to exactly 100.
      - `split_amount` string, nullable — Split amount in percentage or CENTS (`null` for remainder account)

## Response `201`

created

- PeopleBatch — A batch for bulk people creation.
  - `uuid` string, uuid, required — The unique identifier of the people batch.
  - `idempotency_key` string, uuid, required — The idempotency key provided when creating the batch.
  - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'partial_success', required — The current status of the batch processing.
  - `batch_action` string, required — The action being performed on the batch.

## Other responses

- `404` — Not Found
- `409` — conflict - idempotency key already used
- `422` — unprocessable entity - validation errors

---

[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)