> ## Documentation Index > Fetch the complete documentation index at: https://docs.nmbr.co/llms.txt > Use this file to discover all available pages before exploring further. # Bulk Recurrence Operations ## Asynchronous Execution Bulk recurrence operations are asynchronous. Every bulk endpoint returns an [`async_task`](/api-reference/async-tasks/retrieve-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`](/api/overview/webhook-structure) webhook event, which fires when the task finishes. `data.results` contains one entry per affected recurrence — only the `id` and `object`. To retrieve full recurrence bodies, follow up with a list query (filtered by the returned IDs) or fetch individual entities 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 Recurrences Nmbr's API allows you to create a recurrence for select work assignments within a single business entity. This endpoint is useful when you need to create recurrences on one or more work assignments in one API call, such as adding a recurring allowance or benefit to a group of employees. ### Endpoint `POST /s/bulk/create` `` can be one of the following types: * `allowance` * `deduction` * `earning` * `employee_benefit` * `employer_benefit` * `pay_rate` * `reimbursement` For `overtime_rate` bulk operations, see [Bulk Overtime Rate Operations](#bulk-overtime-rate-operations) below. ### Request ```json theme={null} { "business_entity_id": ULID, "work_assignments": { "include": "all" | criteria object, "exclude": criteria object (optional) }, "data": { ...type-specific recurrence properties... } } ``` #### 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 of the recurrence to create | The `data` object contains any recurrence properties specific to the type of recurrence being created. For example, for allowances: | Property | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------ | | `allowance_type` | Type of allowance (e.g., `"cell_phone_allowance"`, `"internet_allowance"`, `"taxable_cash_allowance"`) | | `business_preset_id` | ID of a business preset to use as template | | `title` | Title for the recurrence | | `amount` | Amount for the recurrence | | `frequency` | Frequency for the recurrence (e.g., `"once"`, `"per_payroll"`, `"per_month"`) | | `expense_accounting_code_id` | ID of the expense accounting code | | `liability_accounting_code_id` | ID of the liability accounting code | | `effective_from` | Date the recurrence begins | | `effective_to` | Date the recurrence ends | These properties are documented in more detail in the API reference for each recurrence type. #### Request Criteria Objects `include` and `exclude` can be objects with one 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 include archived work assignments, `false` (default) to exclude them `include` can also be the string `"all"` to include all work assignments. ### Response On success, the operation returns `202 Accepted` with an [`async_task`](/api-reference/async-tasks/retrieve-an-async-task) handle. See [Asynchronous Execution](#asynchronous-execution) for how to track completion. **⚠️ Partners must treat any 200-level response as success. ⚠️** For example, the response might look like: ```json theme={null} { "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 recurrence: ```json theme={null} { "id": "asnct_01KS0G8Z2YD3T9KQNFW1XEA7HB", "object": "async_task", "data": { "type": "bulk_create", "status": "completed", "completed_at": "2026-05-19T16:14:35Z", "results": [ { "id": "alw_01J8KXC9R4MQVW2FXZN7Y5H3B8", "object": "allowance" }, { "id": "alw_01KBMZDVV9G7713DJRYP9RJFTP", "object": "allowance" } ], "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 recurrence properties will be applied to all selected work assignments. * When using a `business_preset_id`, properties must either be omitted or match the preset's values. * The operation only affects work assignments within the specified business entity. Work assignments in other business entities will not be affected. * 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 #### Create a recurring allowance on all work assignments `POST /allowances/bulk/create` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": "all" }, "data": { "allowance_type": "cell_phone_allowance", "title": "Cell Phone Allowance", "amount": 100.0, "frequency": "per_payroll", "effective_from": "2026-01-01" } } ``` #### Create a recurring allowance using a business preset `POST /allowances/bulk/create` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": "all" }, "data": { "business_preset_id": "rps_01J8KXD3M7RQWN2FXZV9Y4H6B1", "amount": 100.0, "frequency": "per_payroll", "effective_from": "2026-01-01" } } ``` #### Create recurring allowances for specific work assignments `POST /allowances/bulk/create` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": { "ids": [ "wrkas_01J8KXB4N6RQWM2FVZH9Y3T5C8", "wrkas_01J8KXB7P2MQVW4RXZN6Y8H3F1", "wrkas_01J8KXBA3TWQNM7FXZR9Y2V5C4" ] } }, "data": { "allowance_type": "cell_phone_allowance", "title": "Cell Phone Allowance", "amount": 100.0, "frequency": "per_payroll", "effective_from": "2026-01-01" } } ``` #### Create recurring allowances on all employee work assignments, excluding specific work assignments (and implicitly excluding contractor work assignments) `POST /allowances/bulk/create` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": { "payee_type": "employee" }, "exclude": { "ids": ["wrkas_01J8KXB4N6RQWM2FVZH9Y3T5C8"] } }, "data": { "allowance_type": "cell_phone_allowance", "title": "Cell Phone Allowance", "amount": 100.0, "frequency": "per_payroll", "expense_accounting_code_id": "accod_01J8KXF2N4MQRW3VXZH7Y9B5C8", "liability_accounting_code_id": "accod_01J8KXF5P6RQNW4MXZV8Y2H7F1", "effective_from": "2026-01-01" } } ``` ## Bulk Create Recurrences Scope The create scope endpoint previews which work assignments will have new recurrences created on them by a bulk create operation. It accepts the same request body as the bulk create endpoint, but instead of creating recurrences, it returns the work assignments that match the criteria. This is useful for confirming which work assignments a bulk create will affect before executing it. ### Endpoint `POST /s/bulk/create/scope` `` can be one of the following types: * `allowance` * `deduction` * `earning` * `employee_benefit` * `employer_benefit` * `pay_rate` * `reimbursement` For `overtime_rate` bulk operations, see [Bulk Overtime Rate Operations](#bulk-overtime-rate-operations) below. ### Request The request body is the same as the [bulk create](#bulk-create-recurrences) endpoint. ### Response On success, the operation will return `200 OK` with an array of work assignments that the bulk create would create recurrences on: ```json theme={null} { "data": [ { "id": "wrkas_01J8KXB4N6RQWM2FVZH9Y3T5C8", "data": { ...work assignment properties... } }, ... ] } ``` ## Bulk Update Recurrences Nmbr's API allows you to update all recurrences of a single type on select work assignments within a single business entity. This endpoint is useful when you need to update the same property on one or more recurrences in one API call, such as changing the amount or accounting code on a group of recurrences. ### Endpoint `POST /s/bulk/update` `` can be one of the following types: * `allowance` * `deduction` * `earning` * `employee_benefit` * `employer_benefit` * `pay_rate` * `reimbursement` For `overtime_rate` bulk operations, see [Bulk Overtime Rate Operations](#bulk-overtime-rate-operations) below. ### Request ```json theme={null} { "business_entity_id": "string", "work_assignments": { "include": "all" | criteria object, "exclude": criteria object (optional) }, "business_presets": { "include": { "ids": [...] }, "exclude": { "ids": [...] } }, "expense_accounting_codes": { "include": { "ids": [...] }, "exclude": { "ids": [...] } }, "liability_accounting_codes": { "include": { "ids": [...] }, "exclude": { "ids": [...] } }, "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 | | `business_presets.include.ids` | array of ULIDs or `null` | No | Only update recurrences with one of these business preset IDs. Use `null` to match recurrences with no business preset. | | `business_presets.exclude.ids` | array of ULIDs or `null` | No | Exclude recurrences with one of these business preset IDs. Use `null` to exclude recurrences with no business preset. | | `expense_accounting_codes.include.ids` | array of ULIDs or `null` | No | Only update recurrences with one of these expense accounting code IDs. Use `null` to match recurrences with no expense accounting code. | | `expense_accounting_codes.exclude.ids` | array of ULIDs or `null` | No | Exclude recurrences with one of these expense accounting code IDs. Use `null` to exclude recurrences with no expense accounting code. | | `liability_accounting_codes.include.ids` | array of ULIDs or `null` | No | Only update recurrences with one of these liability accounting code IDs. Use `null` to match recurrences with no liability accounting code. | | `liability_accounting_codes.exclude.ids` | array of ULIDs or `null` | No | Exclude recurrences with one of these liability accounting code IDs. Use `null` to exclude recurrences with no liability accounting code. | | `data` | object | Yes | The properties to update on the matching recurrences | The `data` object contains any recurrence properties to update. These are the same properties accepted by the single-resource update endpoint for each recurrence type, and are documented in the API reference for each type. #### Work Assignment Criteria Objects `include` and `exclude` can be objects with one 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 include archived work assignments, `false` (default) to exclude them `include` can also be the string `"all"` to include all work assignments. ### Response On success, the operation returns `202 Accepted` with an [`async_task`](/api-reference/async-tasks/retrieve-an-async-task) handle whose `data.results` enumerates the updated recurrences. See [Asynchronous Execution](#asynchronous-execution) for how to track completion and [Bulk Create Recurrences › Response](#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 recurrence fails per-model validation, the entire request fails and no recurrences are updated. ### Notes * The same update properties will be applied to all selected recurrences. * The operation only affects work assignments within the specified business entity. * The `work_assignments` criteria select which work assignments to look under. The `business_presets`, `expense_accounting_codes`, and `liability_accounting_codes` criteria further filter which recurrences under those work assignments are updated. ### Examples #### Update the amount on all recurring allowances `POST /allowances/bulk/update` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": "all" }, "data": { "amount": 150.0 } } ``` #### Update the accounting code on all recurring allowances from a specific business preset `POST /allowances/bulk/update` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": "all" }, "business_presets": { "include": { "ids": ["rps_01J8KXD3M7RQWN2FXZV9Y4H6B1"] } }, "data": { "expense_accounting_code_id": "accod_01J8KXF2N4MQRW3VXZH7Y9B5C8" } } ``` #### Update recurring allowances that have no business preset `POST /allowances/bulk/update` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": "all" }, "business_presets": { "include": { "ids": [null] } }, "data": { "amount": 200.0 } } ``` ## Bulk Update Recurrences Scope The update scope endpoint previews which recurrences will be updated by a bulk update operation. It accepts the same request body as the bulk update endpoint, but instead of updating recurrences, it returns the recurrences that match the criteria. ### Endpoint `POST /s/bulk/update/scope` `` can be one of the following types: * `allowance` * `deduction` * `earning` * `employee_benefit` * `employer_benefit` * `pay_rate` * `reimbursement` For `overtime_rate` bulk operations, see [Bulk Overtime Rate Operations](#bulk-overtime-rate-operations) below. ### Request The request body is the same as the [bulk update](#bulk-update-recurrences) endpoint. ### Response On success, the operation will return `200 OK` with an array of the recurrences that would be updated: ```json theme={null} { "data": [ { "id": "alw_01J8KXC9R4MQVW2FXZN7Y5H3B8", "data": { ...recurrence properties... } }, ... ] } ``` ## Bulk Delete Recurrences Nmbr's API allows you to delete all recurrences of a single type on select work assignments within a single business entity. This endpoint is useful when you need to remove recurrences on one or more work assignments in one API call. **Important:** This operation deletes ALL recurrences of the specified type on the work assignments, not specific recurrences. If you want to delete specific recurrences, you should use the batch delete recurrences endpoints instead. ### Endpoint `POST /s/bulk/delete` `` can be one of the following types: * `allowance` * `deduction` * `earning` * `employee_benefit` * `employer_benefit` * `pay_rate` * `reimbursement` For `overtime_rate` bulk operations, see [Bulk Overtime Rate Operations](#bulk-overtime-rate-operations) below. ### Request ```json theme={null} { "business_entity_id": "string", "work_assignments": { "include": "all" | criteria object, "exclude": criteria object (optional) }, "business_presets": { "include": { "ids": [...] }, "exclude": { "ids": [...] } }, "expense_accounting_codes": { "include": { "ids": [...] }, "exclude": { "ids": [...] } }, "liability_accounting_codes": { "include": { "ids": [...] }, "exclude": { "ids": [...] } } } ``` #### 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 | | `business_presets.include.ids` | array of ULIDs or `null` | No | Only delete recurrences with one of these business preset IDs. Use `null` to match recurrences with no business preset. | | `business_presets.exclude.ids` | array of ULIDs or `null` | No | Exclude recurrences with one of these business preset IDs. Use `null` to exclude recurrences with no business preset. | | `expense_accounting_codes.include.ids` | array of ULIDs or `null` | No | Only delete recurrences with one of these expense accounting code IDs. Use `null` to match recurrences with no expense accounting code. | | `expense_accounting_codes.exclude.ids` | array of ULIDs or `null` | No | Exclude recurrences with one of these expense accounting code IDs. Use `null` to exclude recurrences with no expense accounting code. | | `liability_accounting_codes.include.ids` | array of ULIDs or `null` | No | Only delete recurrences with one of these liability accounting code IDs. Use `null` to match recurrences with no liability accounting code. | | `liability_accounting_codes.exclude.ids` | array of ULIDs or `null` | No | Exclude recurrences with one of these liability accounting code IDs. Use `null` to exclude recurrences with no liability accounting code. | #### Work Assignment Criteria Objects `include` and `exclude` can be objects with one 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 include archived work assignments, `false` (default) to exclude them `include` can also be the string `"all"` to include all work assignments. ### Response On success, the operation returns `202 Accepted` with an [`async_task`](/api-reference/async-tasks/retrieve-an-async-task) handle whose `data.results` enumerates the deleted recurrences (still surfaced by ID — the records soft-delete and remain queryable). See [Asynchronous Execution](#asynchronous-execution) for how to track completion and [Bulk Create Recurrences › Response](#response) for an example response shape — `data.type` will be `bulk_delete`. **⚠️ Partners must treat any 200-level response as success. ⚠️** On failure, the operation will return `422 Unprocessable Entity` with standard validation messages. ### Notes * The operation only affects work assignments within the specified business entity. Work assignments in other business entities will not be affected. * 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. * The `work_assignments` criteria select which work assignments to look under. The `business_presets`, `expense_accounting_codes`, and `liability_accounting_codes` criteria further filter which recurrences under those work assignments are deleted. ### Examples #### Delete all recurring allowances on all work assignments in a business\_entity `POST /allowances/bulk/delete` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": "all" } } ``` #### Delete recurring allowances on specific work assignments `POST /allowances/bulk/delete` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": { "ids": [ "wrkas_01J8KXB4N6RQWM2FVZH9Y3T5C8", "wrkas_01J8KXB7P2MQVW4RXZN6Y8H3F1", "wrkas_01J8KXBA3TWQNM7FXZR9Y2V5C4" ] } } } ``` #### Delete recurring allowances for all employees, excluding specific work assignments `POST /allowances/bulk/delete` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": { "payee_type": "employee" }, "exclude": { "ids": ["wrkas_01J8KXB4N6RQWM2FVZH9Y3T5C8"] } } } ``` #### Delete recurring allowances for all work assignments except contractors `POST /allowances/bulk/delete` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": "all", "exclude": { "payee_type": "contractor" } } } ``` #### Delete only recurring allowances from a specific business preset `POST /allowances/bulk/delete` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": "all" }, "business_presets": { "include": { "ids": ["rps_01J8KXD3M7RQWN2FXZV9Y4H6B1"] } } } ``` #### Delete recurring allowances that have no business preset `POST /allowances/bulk/delete` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": "all" }, "business_presets": { "include": { "ids": [null] } } } ``` #### Delete recurring allowances with a specific expense accounting code `POST /allowances/bulk/delete` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": "all" }, "expense_accounting_codes": { "include": { "ids": ["accod_01J8KXF2N4MQRW3VXZH7Y9B5C8"] } } } ``` ## Bulk Delete Recurrences Scope The delete scope endpoint previews which recurrences will be deleted by a bulk delete operation. It accepts the same request body as the bulk delete endpoint, but instead of deleting recurrences, it returns the recurrences that match the criteria. ### Endpoint `POST /s/bulk/delete/scope` `` can be one of the following types: * `allowance` * `deduction` * `earning` * `employee_benefit` * `employer_benefit` * `pay_rate` * `reimbursement` For `overtime_rate` bulk operations, see [Bulk Overtime Rate Operations](#bulk-overtime-rate-operations) below. ### Request The request body is the same as the [bulk delete](#bulk-delete-recurrences) endpoint. ### Response On success, the operation will return `200 OK` with an array of the recurrences that would be deleted: ```json theme={null} { "data": [ { "id": "alw_01J8KXC9R4MQVW2FXZN7Y5H3B8", "data": { ...recurrence properties... } }, ... ] } ``` ## Bulk Overtime Rate Operations Overtime rate bulk operations follow the same shape as the other recurrence bulk operations, with one addition: because an overtime rate is attached to a pay rate (not directly to a work assignment), the request body accepts a `pay_rates` criteria block to further narrow the pay rates the operation applies to within the matching work assignments. ### Endpoints * `POST /overtime_rates/bulk/create` * `POST /overtime_rates/bulk/create/scope` * `POST /overtime_rates/bulk/update` * `POST /overtime_rates/bulk/update/scope` * `POST /overtime_rates/bulk/delete` * `POST /overtime_rates/bulk/delete/scope` ### Request ```json theme={null} { "business_entity_id": ULID, "work_assignments": { "include": "all" | criteria object, "exclude": criteria object (optional) }, "pay_rates": { "include": "all" | criteria object, "exclude": criteria object (optional) }, "data": { ...overtime rate properties... } } ``` Update and delete requests additionally accept the `business_presets`, `expense_accounting_codes`, and `liability_accounting_codes` filters described in the [Bulk Update Recurrences](#bulk-update-recurrences) section. #### Pay Rate Criteria Objects `pay_rates.include` can be either the string `"all"` or an object with one of: * `ids`: array of pay rate IDs * `subtypes`: array of pay rate types (e.g. `"hourly"`, `"salary"`) `pay_rates.exclude` is optional and accepts the same object shape (without `"all"`). ### Scope The scope variant of each endpoint accepts the same request body and returns the entities the bulk operation would affect: * `bulk/create/scope` returns the pay rates the new overtime rates would be created under. * `bulk/update/scope` returns the overtime rates that would be updated. * `bulk/delete/scope` returns the overtime rates that would be deleted. ### Examples #### Create overtime rates on all hourly pay rates for a business entity `POST /overtime_rates/bulk/create` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": "all" }, "pay_rates": { "include": { "subtypes": ["hourly"] } }, "data": { "rate_multiplier": 1.5 } } ``` #### Delete all overtime rates on specific pay rates `POST /overtime_rates/bulk/delete` ```json theme={null} { "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6", "work_assignments": { "include": "all" }, "pay_rates": { "include": { "ids": ["payrt_01J8KXB4N6RQWM2FVZH9Y3T5C8"] } } } ```