How to use Bulk Operations
Create or update employees, equipment, and locations in bulk, then check operation status and handle record-level errors.
Use bulk operations to create or update employees, equipment, and locations in HeavyJob, Safety and Telematics without submitting each record one request at a time.
Prerequisites
Before starting, ensure you have the following:
- Access to the APIs needed for the records you want to create or update.
- An API client with a client ID and secret. The token must include
setups:readandsetups:write. - Request data prepared for the bulk endpoint you plan to use.
Refer to the Getting Started with Request Tokens guide for details on how to authenticate.
How Bulk Operations Work
Bulk operations allow you to submit a group of records in a single request. Each bulk endpoint can create or update up to 10,000 records.
Bulk endpoints create records in HeavyJob, Safety, and Telematics. To create records for only one product, use the single-record creation endpoint, or use the relevant DELETE endpoint after creation to remove an unwanted product association.
Bulk processing is asynchronous. After you submit a bulk request, the API starts processing the records and returns an operation identifier. Use that identifier to check the status of the bulk operation.
Step 1: Choose the Bulk Endpoint
Select the bulk endpoint that matches the type of records you want to create or update.
Employees
Use the PATCH Creates or updates employees endpoint to create or update employees on given business units.
Equipment
Use the PATCH Creates or updates equipment endpoint to create or update equipment on given business units.
Locations (Jobs)
Use the PATCH Creates or updates locations endpoint to create or update locations on given business units.
Locations are business-unit specific. Submit each location with the correct business unit information.
Step 2: Submit the Bulk Request
Send the request body to the selected bulk endpoint. The endpoint creates new records or updates existing records based on the data you provide.
Each request can include up to 10,000 records. If you need to process more than 10,000 records, split the data into multiple bulk requests.
After the request is accepted, save the operation identifier returned by the API. You need this value to check the processing status.
Step 3: Check the Bulk Operation Status
After you submit a bulk operation request, the response includes a status URL. Use this URL to view processing status, failed records, and product-specific operation details.
You can also use the GET Returns the status of a bulk operation endpoint with the operation identifier to check status programmatically.
Check the status endpoint until the operation has finished processing. Review the status response to confirm which records were created or updated and which records failed.
Error Handling
Bulk operation errors can affect different systems depending on where the failure occurs.
When an operation fails, the status page or status response provides information about the fields that caused the error.
If an individual entity fails validation, that entity is not created or updated. Correct the failed entity and resubmit it. However, other records in the same bulk request that passed validation are still created or updated. You do not need to resubmit the entire bulk request if only some records failed.
Telematics Failures
If Telematics fails, the record may still pass in Safety and HeavyJob. For example, a field that requires a valid year can fail in Telematics when the value is not a valid four-digit year.
HeavyJob Failures
If HeavyJob fails, the record is not created in HeavyJob or Safety.
Safety Failures
If Safety fails, the record can still be created in Telematics and HeavyJob.
Next Steps
After the bulk operation completes, review any failed records from the status response. Correct the failed values and submit those records again using the same bulk endpoint you used in Step 1.
Updated 14 days ago