Skip to main content
Nmbr’s API exposes a family of POST /<entity>/search endpoints that return entities matching a structured selection-criteria payload. They are useful when you need to find or preview a set of entities — typically before deciding whether to perform a bulk operation on them. These endpoints are distinct from the simple search query parameter accepted by some GET list endpoints, which performs a text match against names. Advanced search endpoints accept a JSON body and support structured filters on relationships and attributes.

​
Relationship to Bulk Operations

Each advanced search endpoint accepts the same selection-criteria grammar as the corresponding bulk update and bulk delete endpoints, minus any bulk-only restrictions:
  • The payroll does not have to be in draft status.
  • Managed line items are included in the results.
This makes advanced search useful for tooling that needs to browse or preview entities regardless of payroll state, while bulk operations apply only to entities the caller may mutate. If you want to preview which entities a specific bulk operation would affect — with the bulk-only restrictions applied — use the corresponding scope endpoint instead.

​
Endpoints

EndpointReturns
POST /pay_stubs/searchPay stubs in a payroll
POST /work_assignments/searchWork assignments in a business entity
POST /pay_rates/searchPay rates under matching work assignments
POST /overtime_rates/searchOvertime rates under matching pay rates
POST /<recurrence_type>s/searchRecurrences under matching work assignments
POST /<line_item_type>_line_items/searchLine items on matching pay stubs
<recurrence_type> is one of:
  • allowance
  • deduction
  • earning
  • employee_benefit
  • employer_benefit
  • reimbursement
<line_item_type> is one of:
  • allowance
  • deduction
  • earning
  • employee_benefit
  • employer_benefit
  • reimbursement

​
Request Shape

The request body always identifies a parent scope and one or more criteria objects. Two parent scopes are used across the family:
  • Payroll-scoped endpoints (pay_stubs, line items): require payroll_id and accept pay_stubs.include / pay_stubs.exclude.
  • Business-entity-scoped endpoints (work_assignments, pay_rates, overtime_rates, recurrences): require business_entity_id and accept work_assignments.include / work_assignments.exclude.

​
Pay Stub Criteria

Used by /pay_stubs/search and the line item search endpoints. pay_stubs.include can be either the string "all" or an object with one of:
  • ids: array of pay stub IDs
  • payee_type: "employee" or "contractor"
pay_stubs.exclude is optional and accepts the same object shape (without "all").

​
Work Assignment Criteria

Used by /work_assignments/search, /pay_rates/search, /overtime_rates/search, and the recurrence search endpoints. work_assignments.include can be either the string "all" or an object with one of:
  • ids: array of work assignment IDs
  • payee_type: "employee" or "contractor"
  • pay_schedule_id: ID of a pay schedule
  • archived: true to match archived work assignments, false to match active ones
  • payee_names: string matched against the payee’s name
work_assignments.exclude is optional and accepts the same object shape (without "all").

​
Additional Criteria

Recurrence and line item search endpoints accept additional filters that narrow the matched entities under the selected parents:
  • business_presets.include.ids / business_presets.exclude.ids: filter by the entity’s business preset. Use null in the array to match entities with no business preset.
  • expense_accounting_codes.include.ids / expense_accounting_codes.exclude.ids: filter by expense accounting code. Use null to match entities with no expense accounting code.
  • liability_accounting_codes.include.ids / liability_accounting_codes.exclude.ids: filter by liability accounting code. Use null to match entities with no liability accounting code.
Recurrence search endpoints additionally accept:
  • effective_from / effective_to: filter by the recurrence’s effective date range.
  • subtype: filter by the recurrence subtype (e.g. cell_phone_allowance, bonus_discretionary).
  • ids: filter to a specific set of recurrence IDs.
Refer to the API reference for each endpoint for the exhaustive list of supported criteria.

​
Response

Each endpoint returns 200 OK with a paginated collection of the matching entities, in the same shape as the corresponding GET list endpoint. 
{
  "data": [
    {
      "id": "alw_01J8KXC9R4MQVW2FXZN7Y5H3B8",
      "data": {
        ...entity properties...
      }
    },
    ...
  ]
}
On failure, the endpoint returns 422 Unprocessable Entity with standard validation messages.

​
Examples

​
Find all pay stubs in a payroll

POST /pay_stubs/search 
{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": "all"
  }
}

​
Find work assignments by payee name

POST /work_assignments/search 
{
  "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "work_assignments": {
    "include": {
      "payee_names": "Smith"
    }
  }
}

​
Find all recurring allowances tied to a specific business preset

POST /allowances/search 
{
  "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "work_assignments": {
    "include": "all"
  },
  "business_presets": {
    "include": {
      "ids": ["rps_01J8KXD3M7RQWN2FXZV9Y4H6B1"]
    }
  }
}

​
Find earning line items on contractor pay stubs

POST /earning_line_items/search 
{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": {
      "payee_type": "contractor"
    }
  }
}