Skip to main content
Nmbr supports a number of bulk and batch operations for managing multiple recurrences, line items, and other objects in one API call: The distinction between “bulk” and “batch” is subtle but important.

​
Bulk Operations

Bulk operations
  • take criteria objects that define the criteria used to select the objects to perform the bulk operation on,
  • find all objects matching the criteria, and
  • perform the same operation on each object.
For example, the bulk operations for line items take criteria objects that define which pay stubs’ line items will be affected by the operation. Example: Create earning line items on all non-contractor pay stubs in a payroll POST /earning_line_items/bulk/create
Example: Update all earning line items with a specific business preset on all pay stubs in a payroll POST /earning_line_items/bulk/update
Example: Delete all earning line items on all pay stubs in a payroll POST /earning_line_items/bulk/delete

​
Scope Endpoints

Every bulk operation has a corresponding scope endpoint that previews which entities will be affected by the operation, without performing it. Scope endpoints accept the same request body as their corresponding bulk operation and return the entities that would be affected. The scope endpoint URL is the bulk operation URL with /scope appended: What the scope endpoint returns depends on the operation:
  • Create scope returns the parent entities the new entities will be created under (e.g. pay stubs for line items, work assignments for recurrences, payees for work assignments, work assignments for pay stubs).
  • Update scope returns the entities that will be updated.
  • Delete scope returns the entities that will be deleted.
Work assignments don’t support a bulk delete, so they have no delete scope endpoint. See Bulk Line Item Operations, Bulk Recurrence Operations, Bulk Work Assignment Operations, and Bulk Pay Stub Operations for details on the scope endpoints for each type.

​
Batch Operations

Batch operations take one object or ID for each entity to perform the batch operation on. For example, the batch upsert operations for line items take one object per line item, and will create or update each line item with that object’s properties. For example, the batch delete operations for line items take one ID per line item, and will delete the line item with that ID.

​
Comparing Bulk and Batch Operations

Bulk operations take criteria objects and perform the operation on 0..n entities, all with the same properties. Batch operations take objects or IDs and perform the operation on each entity, 1:1, with different properties per object.

​
Asynchronous Execution

All bulk and batch mutating operations are asynchronous: they return 202 Accepted with an async_task handle. The task may or may not have completed by the time the response arrives — partners must always check data.status (poll links.self, or subscribe to the async_task_completed webhook). See Batch Operations, Bulk Line Item Operations, Bulk Recurrence Operations, Bulk Work Assignment Operations, and Bulk Pay Stub Operations for the per-section details. Scope endpoints are synchronous previews with no side effects.