Bulk Recurrence Operations

Asynchronous Execution

Bulk recurrence 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 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 /<type>s/bulk/create <type> 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 below.

Request

{
  "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 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 recurrence:

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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 /<type>s/bulk/create/scope <type> 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 below.

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 work assignments that the bulk create would create recurrences on:

{
  "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 /<type>s/bulk/update <type> 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 below.

Request

{
  "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 handle whose data.results enumerates the updated recurrences. See Asynchronous Execution for how to track completion and Bulk Create Recurrences › 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

{
  "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

{
  "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

{
  "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 /<type>s/bulk/update/scope <type> 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 below.

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 recurrences that would be updated:

{
  "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 /<type>s/bulk/delete <type> 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 below.

Request

{
  "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 handle whose data.results enumerates the deleted recurrences (still surfaced by ID — the records soft-delete and remain queryable). See Asynchronous Execution for how to track completion and Bulk Create Recurrences › 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.