Get the status of a people batch

GET /v1/people_batches/{batch_uuid} returns the status and the detailed results of the given uploaded batch based on its batch_uuid.

The batch_uuid is the unique identifier that the caller provided during the upload. This allows the caller to track the progress and results of the batch operation.

Scope: people_batches:read

The endpoint returns one of the following:

200 OK : batch results are returned
404 Not Found: unknown batch_uuid
422 Unprocessable Entity: when there is an internal issue with the batch result data

Response details

The response is a JSON object containing:

status: (e.g., "pending", "processing", "success", “partial_success”, "failed")
- pending : none of the entities have been started yet
- processing : one or more of the entities are still processing
- success : all entities are in a successfully completed state
- partial_success: all entities have been processed, 1 or more items or attributes have errors
- failed : the entire batch did not process for some reason
submitted_at: timestamp of the upload.
completed_at: timestamp of completion (if applicable), or NULL
submitted_items: Integer
processed_items: Integer
excluded_items: Integer
results: An array detailing the outcome for each person in the batch. This could include:
- For create requests: Gusto's uuid and the partner's external_id of the person.
- For update requests: Gusto's uuid
- The operation performed (create or update).
- The final internal UUID (if creation was successful).
- idx : the index of the person corresponding to the batch input data
- Overall status for this person:
  - success everything worked
  - failed: incl. any validation errors for this person
  - partial_success: indicates a partial success, and we provide the status for each attribute (success or failure)
When an attribute or person has partial failures, those can be safely retried as part of a new batch request (idempotent operations).
exclusions: An array of employee objects. In case there are general issues with an employee's data, e.g. duplicate records with identical external_id, ssn, email, or work_email, these records will not be processed, and appear in this array.

📘
idx
For data submitted as arrays, such as people or bank accounts, in the errors responses you will see the index (idx) that corresponds to the index that item had in the input data .

Example response

{
  "batch_uuid": "9f879a17-7166-4b5e-9266-334a642898c6",
  "batch_status": "partial_success",
  "submitted_at": "2025-04-11T01:22:38Z",
  "completed_at": "2025-04-11T01:35:12Z",
  "submitted_items": 5,
  "processed_items": 3,
  "excluded_items": 2,
  "results": [
    {
      "idx": 0,
      "external_id": "employee-abc-123",
      "entity_type": "employee",
      "uuid": "e456-7890-abcd-efgh",
      "status": "success"
    },
    {
      "idx": 1,
      "external_id": "employee-xyz-456",
      "entity_type": "employee",
      "uuid": "f123-4567-89ab-cdef",
      "employee_uuid": "f123-4567-89ab-cdef",
      "status": "partial_success", // Overall status for this specific people item
      "errors": [ // The 'errors' field is a top-level ARRAY for this item
        { // Error for the 'email' attribute
          "error_key": "email",
          "category": "invalid_attribute_value",
          "message": "Invalid email format"
        },
        { // Second error for the 'email' attribute (if applicable)
          "error_key": "email", // Use the same error_key for another issue with 'email'
          "category": "duplicate_value",
          "message": "Email address is already in use by another employee."
        },
        { // Nested errors for 'home_address', which is a nested entity
          "error_key": "home_address", // Identifies the nested entity
          "category": "nested_errors", // Signals that its 'errors' array contains sub-errors
          "status": "partial_success", // each entity has its own status
          // Optional: "metadata": { "address_uuid": "..." } for the UUID of the 'home_address'
          "errors": [ // Nested 'errors' array for 'home_address' sub-fields
            {
              "error_key": "zip_code",
              "category": "invalid_attribute_value",
              "message": "Invalid zip code format"
            },
            {
              "error_key": "zip_code", // Another error for the 'zip_code' sub-field
              "category": "geographic_mismatch",
              "message": "Zip code does not match the provided city and state."
            }
          ]
        }
      ]
    },
    {
      "idx": 2,
      "external_id": "employee-pqr-789",
      "entity_type": "employee",
      "status": "failed", // Overall status for this specific employee item
      "errors": [ // The 'errors' field is now a top-level ARRAY for this item
        { // Base error for the employee item
          "error_key": "base", // Or a more specific key if applicable (e.g., "duplicate_external_id")
          "category": "internal_error",
          "message": "Database connection error: Unable to connect to payroll service."
        },
        { // Another general error for the employee item
          "error_key": "system_unavailable",
          "category": "internal_error", // Or "system_error" if a distinct category is needed
          "message": "Payroll processing is temporarily unavailable. Please try again later."
        }
      ]
    }
  ],   "exclusions": [ // records that were not processed because of general issues
    {
      "external_id": "employee-pqr-999", // a duplicated external_id value
      "reason_code": "invalid_attribute_value",
      "message": "Duplicate 'external_id' found within the batch request. 2 items sharing this ID were excluded from processing.",
      "item_count": 2
    }
  ]
}

Showing only the errors allows the caller to fix errors via our regular API calls, and build on work that was already completed in the batch request.

The above results for the batch will provide the mapping from the partner's external_id to our system's employee_uuid for successfully created employees / entities.