People Batch API

The Gusto Embedded Payroll (GEP) People Batch API streamlines the ability to create W-2 employees by allowing you to submit a batch of employees and their essential information—as you might do when onboarding a company—in a single request.

After asynchronous processing, GEP sends a webhook indicating that batch results are ready to be retrieved.

Although the People Batch API significantly reduces the number of calls required to create W-2 employees—as outlined in the multi-step onboarding process—certain onboarding tasks still need to be completed individually.

• For any employee in the batch who requires additional corrections or supplemental data, continue to use the existing endpoints to resolve issues.
• You will need to update the onboarding status for each of the employees in a batch separately.

Key features

The central feature of this API is to enable the onboarding batches of employees, including sending:

• Mandatory data, such as personal information, incl. self onboarding status
• And data around home address, working-from-home, and work location information, such as:
  • Job and compensation information
  • Paycheck distribution for direct deposits
  • Department information

Additional key features include:

• Asynchronous processing of employee creation
• Reducing complexity creating employees
• Call-back via webhook to get notified of batch completion

Process overview

1. Pick a unique idempotency_key for the batch, to avoid duplicate processing.

2. Make one API call to create a batch of employees, by sending us a JSON payload with all relevant data of the employees.

   For each employee, pass in your employee identifier as external_id. We only store this ephemerally and on completion, we return it along with our employee_uuid, so you can correlate them.

   Minimum required data:

   JSON

   {
     "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"
         }
       }
     ]
   }

   • person (Required)
   • home_address
   • work_address—only specify if the employee does not work from home (specified in home_address)
   • job
   • compensation—job details must be provided if providing compensation details
   • bank_accounts and paycheck distribution
   • department

3. GEP is checks the integrity of the JSON data, and responds with one of the following:

• "201 Created"
  • If the data validation passes, we immediately accept the batch and return 201 Created and the unique batch_uuid. We then process the batch async in parallel. The batch_uuid is required in order to fetch the batch status.
• 409 Conflict when the same idempotency_key is used more than once
• 422 / Unprocessable Entity if the batch data has formatting issues.

4. GEP processes all the provided data asynchronously and creates corresponding entries in our system.

5. After processing concludes, you will receive a webhook indicating the status, either:

   1. people_batch.completed for successful operations
   2. people_batch.failed when there are processing exceptions In either case, you must fetch the batch status after receiving a webhook as described in the next step.
      You can also check the status of the batch at anytime, but we don't recommend polling this endpoint.

6. You fetch the batch results with detailed results, take note of any errors, and get the mapping from their external_id to our employee_uuid. Take note of our employee_uuid for future calls to Gusto Embedded endpoints.

   In the response you will see general information about the batch, and two sections:

   1. "results': Contains information about employees or their data domains, with a status of "success", "partial_success", or "failed". If there are any errors, use our regular API calls to fix those.

   2. "exclusions": If present, contains information about records which could not be processed because of general issues, such as duplicated records, or a duplicated external_id.

      None of the records under exclusions get processed, so you can correct the data and re-submit it as a separate batch.

   In the results and exclusions sections you will see a mention of "idx" which refers to the cardinal index of an item in the JSON payload. e.g. the index 0..N of the employee record in the JSON payload, or the index of a bank account.

FAQ

How do I correlate employees in my system with Gusto Embedded Payroll's employee identifiers?

You will need to correlate your system's identifier with GEP's identifier for each employee. To do this, supply your identifier as external_id in the employee data.

When you check the batch results, your external_id and GEP's employee_uuid will be both be returned so these values can be associated in your system.

GEP's employee_uuid will be required for any subsequent API calls.

How do I handle error states, such as partial success and exclusions?

The goal of this process is to create as much of the provided data as possible in GEP's systems. Should there be any errors, we will surface these in the batch status, and results for individual aspects of an employee may be marked as partial success.

In case of errors, use our regular API endpoints to correct any issues, using the employee_uuid.

Should an employee not be created altogether, their data will show in the batch results under exclusions, and their corrected data can be provided in a future batch.

What scopes are required?

The following scopes are required: people_batches:write to create the different aspects of employee information, andpeople_batches:read to check for batch status.