Bulk Work Assignment Operations

Bulk work assignment operations create or update many work assignments in one API call. They follow the same shape as Bulk Line Item Operations and Bulk Recurrence Operations, with two differences:

Create selects payees (employees and contractors) and creates one work assignment per payee on a pay schedule.
Update selects work assignments directly, within a single business entity.

There is no bulk delete for work assignments.

Asynchronous Execution

Bulk work assignment operations are asynchronous. Every bulk endpoint returns an async_task handle that you use to track completion and retrieve the affected entities. The task may or may not have completed by the time you receive the response. data.status could be processing or completed. Partners must always check data.status and not assume the work has finished. You have two ways to observe completion:

Poll the URL in links.self on the response until data.status is completed (or error).
Subscribe to the async_task_completed webhook event, which fires when the task finishes.

data.results contains one entry per affected work assignment, with only the id and object. To retrieve full work assignment bodies, follow up with a list query (filtered by the returned IDs) or fetch individual work assignments by ID. Note: scope endpoints (/bulk/*/scope) are previews with no side effects and are synchronous - they return 200 OK with the inline list of matched entities.

Bulk Create Work Assignments

Nmbr’s API allows you to create a work assignment for select payees on a single pay schedule. This endpoint is useful when you need to add a group of employees or contractors to a pay schedule in one API call, such as onboarding a new team onto a bi-weekly schedule.

Endpoint

POST /work_assignments/bulk/create

Request

{
  "payees": {
    "include": "all" | criteria object,
    "exclude": criteria object (optional)
  },
  "data": {
    "pay_schedule_id": ULID,
    ...other work assignment properties...
  }
}

Request Properties

Property	Type	Required	Description
`payees.include`	criteria object or `"all"`	Yes	Criteria for selecting payees to include
`payees.exclude`	criteria object	No	Criteria for selecting payees to exclude
`data`	object	Yes	The properties of the work assignment to create, including `pay_schedule_id`

The work assignment’s business entity is taken from the pay schedule, so there is no top-level business_entity_id on create.

Payee Criteria Objects

include and exclude can be objects with one or more of the following properties:

ids: Array of employee/contractor IDs to include or exclude
payee_type: "employee" or "contractor"
payee_names: Name search (partial match)
archived: true to select archived payees, false (default) to select active payees

When you combine properties, they apply together. For example, { "payee_type": "employee", "archived": false } selects active employees only. include can also be the string "all" to include all payees.

Data Properties

The data object contains the work assignment properties to apply to each created work assignment. For example:

Property	Description
`pay_schedule_id`	(Required) The pay schedule to create the work assignment on. Sets the work assignment’s business entity.
`title`	Label for the work assignment
`is_primary`	Whether this is the payee’s primary work assignment
`pay_split_id`	ID of a pay split to apply to the work assignment
`external_ref`	Your external identifier for the work assignment
`archived_at`	Date to archive the work assignment (`YYYY-MM-DD`)
`tax_properties`	Inline tax properties to set on the work assignment
`tag_assignment`	Tag allocations for the work assignment

The payee for each work assignment comes from your selection. Don’t set employee_id or contractor_id in data. These properties are documented in more detail in the API reference for work assignments.

Response

On success, the operation returns 202 Accepted with an async_task handle. See Asynchronous Execution for how to track completion. ⚠️ Partners must treat any 200-level response as success. ⚠️ For example, the response might look like:

{
  "id": "asnct_01KS0G8Z2YD3T9KQNFW1XEA7HB",
  "object": "async_task",
  "data": {
    "type": "bulk_create",
    "status": "processing",
    "completed_at": null,
    "results": [],
    "created_at": "2026-05-19T16:14:32Z",
    "updated_at": "2026-05-19T16:14:32Z"
  },
  "links": {
    "self": "/async_tasks/asnct_01KS0G8Z2YD3T9KQNFW1XEA7HB"
  }
}

Once the task completes, data.results will contain one entry per created work assignment:

{
  "id": "asnct_01KS0G8Z2YD3T9KQNFW1XEA7HB",
  "object": "async_task",
  "data": {
    "type": "bulk_create",
    "status": "completed",
    "completed_at": "2026-05-19T16:14:35Z",
    "results": [
      { "id": "wrkas_01J8KXC9R4MQVW2FXZN7Y5H3B8", "object": "work_assignment" },
      { "id": "wrkas_01KBMZDVV9G7713DJRYP9RJFTP", "object": "work_assignment" }
    ],
    "created_at": "2026-05-19T16:14:32Z",
    "updated_at": "2026-05-19T16:14:35Z"
  },
  "links": {
    "self": "/async_tasks/asnct_01KS0G8Z2YD3T9KQNFW1XEA7HB"
  }
}

On failure, the operation will return 422 Unprocessable Entity with standard validation messages.

Notes

The same work assignment properties (other than the payee) are applied to every created work assignment.
The business entity is taken from the pay schedule. You don’t pass a business_entity_id.
Payees that already have a work assignment on that pay schedule are skipped. There is one work assignment per pay schedule per payee. Skipped payees won’t appear in data.results.
Each new work assignment generates its draft pay stubs on upcoming draft payrolls for that pay schedule, the same as creating a single work assignment.
Validation runs against every selected payee before any work assignment is created. If validation fails, no work assignments are created.
Invalid payee IDs in the include.ids or exclude.ids arrays are silently ignored and won’t cause an error.
When both include and exclude criteria are provided, exclusions are applied after inclusions.

Examples

Create work assignments for all employees on a pay schedule

POST /work_assignments/bulk/create

{
  "payees": {
    "include": {
      "payee_type": "employee"
    }
  },
  "data": {
    "pay_schedule_id": "paysc_01J8KX9R2FMQVW3TNZH5Y7B4C6"
  }
}

Create work assignments for specific payees

POST /work_assignments/bulk/create

{
  "payees": {
    "include": {
      "ids": [
        "emp_01J8KXB4N6RQWM2FVZH9Y3T5C8",
        "emp_01J8KXB7P2MQVW4RXZN6Y8H3F1",
        "cntct_01J8KXBA3TWQNM7FXZR9Y2V5C4"
      ]
    }
  },
  "data": {
    "pay_schedule_id": "paysc_01J8KX9R2FMQVW3TNZH5Y7B4C6",
    "title": "Engineering",
    "is_primary": true
  }
}

Create work assignments for all payees, excluding specific payees

POST /work_assignments/bulk/create

{
  "payees": {
    "include": "all",
    "exclude": {
      "ids": ["emp_01J8KXB4N6RQWM2FVZH9Y3T5C8"]
    }
  },
  "data": {
    "pay_schedule_id": "paysc_01J8KX9R2FMQVW3TNZH5Y7B4C6"
  }
}

Create work assignments with a pay split for all contractors

POST /work_assignments/bulk/create

{
  "payees": {
    "include": {
      "payee_type": "contractor"
    }
  },
  "data": {
    "pay_schedule_id": "paysc_01J8KX9R2FMQVW3TNZH5Y7B4C6",
    "pay_split_id": "paysp_01J8KXD3M7RQWN2FXZV9Y4H6B1"
  }
}

Bulk Create Work Assignments Scope

The create scope endpoint previews which payees will receive a new work assignment from a bulk create operation. It accepts the same request body as the bulk create endpoint, but instead of creating work assignments, it returns the payees that match the criteria. Because the work assignments don’t exist yet, this endpoint returns payees, not work assignments. Payees that already have a work assignment on the target pay schedule are excluded, matching the create behavior. This is useful for confirming which payees a bulk create will affect before executing it.

Endpoint

POST /work_assignments/bulk/create/scope

Request

The request body is the same as the bulk create endpoint.

Response

On success, the operation will return 200 OK with an array of the payees that the bulk create would create work assignments for. The array can contain both employees and contractors:

{
  "data": [
    {
      "id": "emp_01J8KXB4N6RQWM2FVZH9Y3T5C8",
      "data": {
        ...employee or contractor properties...
      }
    },
    ...
  ]
}

Bulk Update Work Assignments

Nmbr’s API allows you to update select work assignments within a single business entity. This endpoint is useful when you need to update the same property on a group of work assignments in one API call, such as moving a team onto a pay split or archiving a set of work assignments.

Endpoint

POST /work_assignments/bulk/update

Request

{
  "business_entity_id": ULID,
  "work_assignments": {
    "include": "all" | criteria object,
    "exclude": criteria object (optional)
  },
  "data": {
    ...properties to update...
  }
}

Request Properties

Property	Type	Required	Description
`business_entity_id`	ULID	Yes	ID of the business entity containing the work assignments
`work_assignments.include`	criteria object or `"all"`	Yes	Criteria for selecting work assignments to include
`work_assignments.exclude`	criteria object	No	Criteria for selecting work assignments to exclude
`data`	object	Yes	The properties to update on the matching work assignments

Work Assignment Criteria Objects

include and exclude can be objects with one or more of the following properties:

ids: Array of work assignment IDs to include or exclude
payee_type: "employee" or "contractor"
pay_schedule_id: ID of the pay schedule to include or exclude
archived: true to select archived work assignments, false (default) to select active ones
payee_names: Name search (partial match)

When you combine properties, they apply together. include can also be the string "all" to include all work assignments.

Data Properties

The data object contains the work assignment properties to update. For example:

Property	Description
`title`	Label for the work assignment
`is_primary`	Whether this is the payee’s primary work assignment
`pay_split_id`	ID of a pay split to apply to the work assignment
`external_ref`	Your external identifier for the work assignment
`archived_at`	Date to archive the work assignment (`YYYY-MM-DD`)
`tag_assignment`	Replaces the work assignment’s tag allocations
`tag_assignment_patch`	Additively modifies the existing tag allocations. Mutually exclusive with `tag_assignment`.

You cannot change a work assignment’s business entity, pay schedule, or payee. Sending business_entity_id, pay_schedule_id, employee_id, or contractor_id in data fails validation. These properties are documented in more detail in the API reference for work assignments.

Response

On success, the operation returns 202 Accepted with an async_task handle whose data.results enumerates the updated work assignments. See Asynchronous Execution for how to track completion and Bulk Create Work Assignments › Response for an example response shape. data.type will be bulk_update. ⚠️ Partners must treat any 200-level response as success. ⚠️ On failure, the operation will return 422 Unprocessable Entity with standard validation messages. If any matched work assignment fails per-model validation, the entire request fails and no work assignments are updated.

Notes

The same update properties are applied to all selected work assignments.
The operation only affects work assignments within the specified business entity.
You cannot change a work assignment’s business entity, pay schedule, or payee.
Validation is all-or-nothing. If any matched work assignment fails validation, the entire request fails and no work assignments are updated.
Invalid work assignment IDs in the include.ids or exclude.ids arrays are silently ignored and won’t cause an error.
When both include and exclude criteria are provided, exclusions are applied after inclusions.

Examples

Update the title on all work assignments

POST /work_assignments/bulk/update

{
  "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "work_assignments": {
    "include": "all"
  },
  "data": {
    "title": "Engineering"
  }
}

Archive work assignments on a specific pay schedule

POST /work_assignments/bulk/update

{
  "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "work_assignments": {
    "include": {
      "pay_schedule_id": "paysc_01J8KX9R2FMQVW3TNZH5Y7B4C6"
    }
  },
  "data": {
    "archived_at": "2026-06-01"
  }
}

Update a pay split for all employees, excluding specific work assignments

POST /work_assignments/bulk/update

{
  "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "work_assignments": {
    "include": {
      "payee_type": "employee"
    },
    "exclude": {
      "ids": ["wrkas_01J8KXB4N6RQWM2FVZH9Y3T5C8"]
    }
  },
  "data": {
    "pay_split_id": "paysp_01J8KXD3M7RQWN2FXZV9Y4H6B1"
  }
}

Add a tag to all work assignments without replacing existing allocations

POST /work_assignments/bulk/update

{
  "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "work_assignments": {
    "include": "all"
  },
  "data": {
    "tag_assignment_patch": {
      "add_tags": ["tag_01J8KXF2N4MQRW3VXZH7Y9B5C8"]
    }
  }
}

Bulk Update Work Assignments Scope

The update scope endpoint previews which work assignments will be updated by a bulk update operation. It accepts the same request body as the bulk update endpoint, but instead of updating work assignments, it returns the work assignments that match the criteria.

Endpoint

POST /work_assignments/bulk/update/scope

Request

The request body is the same as the bulk update endpoint.

Response

On success, the operation will return 200 OK with an array of the work assignments that would be updated:

{
  "data": [
    {
      "id": "wrkas_01J8KXB4N6RQWM2FVZH9Y3T5C8",
      "data": {
        ...work assignment properties...
      }
    },
    ...
  ]
}

​Asynchronous Execution

​Bulk Create Work Assignments

​Endpoint

​Request

​Request Properties

​Payee Criteria Objects

​Data Properties

​Response

​Notes

​Examples

​Create work assignments for all employees on a pay schedule

​Create work assignments for specific payees

​Create work assignments for all payees, excluding specific payees

​Create work assignments with a pay split for all contractors

​Bulk Create Work Assignments Scope

​Endpoint

​Request

​Response

​Bulk Update Work Assignments

​Endpoint

​Request

​Request Properties

​Work Assignment Criteria Objects

​Data Properties

​Response

​Notes

​Examples

​Update the title on all work assignments

​Archive work assignments on a specific pay schedule

​Update a pay split for all employees, excluding specific work assignments

​Add a tag to all work assignments without replacing existing allocations

​Bulk Update Work Assignments Scope

​Endpoint

​Request

​Response

Asynchronous Execution

Bulk Create Work Assignments

Endpoint

Request

Request Properties

Payee Criteria Objects

Data Properties

Response

Notes

Examples

Create work assignments for all employees on a pay schedule

Create work assignments for specific payees

Create work assignments for all payees, excluding specific payees

Create work assignments with a pay split for all contractors

Bulk Create Work Assignments Scope

Endpoint

Request

Response

Bulk Update Work Assignments

Endpoint

Request

Request Properties

Work Assignment Criteria Objects

Data Properties

Response

Notes

Examples

Update the title on all work assignments

Archive work assignments on a specific pay schedule

Update a pay split for all employees, excluding specific work assignments

Add a tag to all work assignments without replacing existing allocations

Bulk Update Work Assignments Scope

Endpoint

Request

Response