GuidesAPI ReferenceChangelogAPI StatusAPI PolicyGusto Security
Guides
Start typing to search…

Create a people batch

POST /v1/companies/#{company_uuid}/people_batches creates a people batch and returns its batch_uuid.

Scope: people_batches:write

Request details

The body of the request is a JSON object that must contain:

  • A unique UUID idempotency_key

    This idempotency_key must be generated on the caller's side to ensure idempotency of requests.
    If the idempotency_key is not unique for the given company, the upload will result in a 409 error.


    📘

    The idempotency_key is the caller's unique identifier for a batch request - it is required to ensure that each batch is only created once. Once a batch is created the response will show the batch_uuid.

  • A batch_action

  • Within the batch, there must be an entity_type, e.g. "employee"

  • Each person object must contain an external_id from your system for create actions.

    • The external_id will not be persisted.

For any other optional attributes, see the API reference or the detailed input section.

Response details

The batch_uuid, Gusto's unique identifier for a batch request, is returned. This is required to later fetch the batch status.

{
  "batch_uuid": "9f879a17-7166-4b5e-9266-334a642898c6",
}
  • 201 Created: Batch accepted and we return the batch_uuid
  • 409 Conflict: When the same idempotency_key is used more than once
  • 422 Unprocessable Entity: When there is an issue with the batch data itself, e.g. JSON validation errors

Examples

Minimum / mandatory inputs for each Employee

{
  "idempotency_key": "bcfc9744-0ab3-4ef3-ab0d-e728255d659c",
  "batch_action" : "create",
  "batch": [
    {
      "entity_type": "employee",
      "person": {
        "external_id": "employee-abc-123",
        "first_name": "Alice",
        "last_name": "Smith"
      }
    }
  ]
}
📘

external_id

As outlined in the Request section of this guide, the external_id is your unique identifier for a person—this will be your employee identifier.

The external_id is used only ephemerally while the batch is processing, and then returned in the batch results alongside the person's employee_uuid. You must associate the Gusto employee_uuid with your external_idin order to reference the person in later API calls.

Full inputs for each Employee's person data

 {
  "idempotency_key": "bcfc9744-0ab3-4ef3-ab0d-e728255d659c",
  "batch_action" : "create",
  "batch": [
    {
      "entity_type": "employee",
      "person": {
        # mandatory:
        "external_id": "employee-abc-123",
        "first_name": "Alice",
        "last_name": "Smith",
        # optional:
        "ssn": "xxx-xx-xxxx",
        "date_of_birth": "1990-05-15",
        "preferred_first_name": "Liza",
        "middle_initial": "J",
        "email": "[email protected]",
        "work_email": "[email protected]",
        "self_onboarding": true
      }
    }
  ]
}

Optional inputs

Only the minimum person data is mandatory—each of these sections is optional:

  • home address , optionally with "work_from_home" status

    • either home address or work location, or both can be provided

    • when home address with "work_from_home" is given, we internally create a new work location,
      and passing-in a work address is not permitted.

  • work address (aka company location; needs to be created via regular API calls)

    • this is taking the UUID of an existing work location

  • job details

  • compensation

  • Bank Accounts and Paycheck Distributions for Direct Deposit.

    • ordered list of bank accounts with splits (all-in-one)

  • Department

    • department_uuid
{
  "idempotency_key": "bcfc9744-0ab3-4ef3-ab0d-e728255d659c",
  "batch_action" : "create",
  "batch": [
    {
      "entity_type": "employee",
      "person": {
        "external_id": "employee-abc-123",
        "ssn": "xxx-xx-xxxx",
        "date_of_birth": "1990-05-15",
        "preferred_first_name": "Liza",
        "first_name": "Alice",
        "middle_initial": "J",
        "last_name": "Smith",
        "email": "[email protected]",
        "work_email": "[email protected]",
        "self_onboarding": false
      },
      "home_address": {
        "street_1": "456 Oak Ave",
        "street_2": "Apt #3",
        "city": "Sunnyvale",
        "state": "CA",
        "zip": "94087",
        "country": "USA"
      },
      "work_address": {
        "location_uuid": "6fd76a95-a887-428c-8cc1-5eb6160af092"
      },
      "department": {
        "department_uuid": "7087a288-8349-4632-b92e-bc94fb79f29e"
      },
      "job": {
        "title": "Software Engineer",
        "hire_date": "2023-08-20",
        "two_percent_shareholder": false
      },
      "compensation": {
        "rate": "160000.0",
        "payment_unit": "Year",
        "effective_date": "2025-01-20",
        "flsa_status": "Salaried Nonexempt"
      },
      "bank_accounts": [
        {
          "name": "BofA Checking",
          "account_type": "Checking",
          "routing_number": "266905059",
          "account_number": "5809431207",
   	      "type": "Direct Deposit",
          "split_by": "Amount",
          "split_amount": "450000"
        },
        {
          // remaining funds go here
          "name": "Etrade Savings",
          "account_type": "Savings",
          "account_number": "1234567890",
          "routing_number": "0987654543",
          "type": "Direct Deposit",
          "split_by": "Amount",
          "split_amount": null
        }
      ]
    },
    {
      "entity_type": "employee",
      "person": {
        "external_id": "employee-def-456",
        "ssn": "yyy-yy-yyyy",
        "date_of_birth": "2002-02-12",
        "first_name": "Bob",
        "middle_initial": null,
        "last_name": "Johnson",
        "self_onboarding": true
      },
      "home_address": {
        "street_1": "789 Pine Ln",
        "city": "Sunnyvale",
        "state": "CA",
        "zip": "94087",
        "country": "USA",
        "work_from_home": true
      },
      // no work address given
      "department": {
        "department_uuid": "7087a288-8349-4632-b92e-bc94fb79f29e"
      },
      "job": {
        "title": "Product Manager",
        "hire_date": "2024-01-15",
        "two_percent_shareholder": false
      },
      "compensation": {
        "rate": "120000.0",
        "payment_unit": "Year",
        "effective_date": "2024-01-15",
        "flsa_status": "Salaried Nonexempt"
      },
      "bank_accounts": [
        {
          "name": "Etrade Checking",
          "account_type": "Checking",
          "account_number": "1234567890",
          "routing_number": "000234234223",
          "type": "Direct Deposit",
          "split_by": "Percentage",
          "split_amount": "80.0"
        },
        {
          // percentages have to add up to 100
          "name": "Etrade Savings",
          "account_type": "Savings",
          "account_number": "1234567890",
          "routing_number": "0987693293",
          "type": "Direct Deposit",
          "split_by": "Percentage",
          "split_amount": "20.0"
        }
      ]
    }
  ]
}

Updated about 17 hours ago