> ## 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.

# Advanced Search

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](./bulk-and-batch-operations#bulk-operations) 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](./bulk-and-batch-operations#scope-endpoints) instead.

## Endpoints

| Endpoint                                   | Returns                                     |
| ------------------------------------------ | ------------------------------------------- |
| `POST /pay_stubs/search`                   | Pay stubs in a payroll                      |
| `POST /work_assignments/search`            | Work assignments in a business entity       |
| `POST /pay_rates/search`                   | Pay rates under matching work assignments   |
| `POST /overtime_rates/search`              | Overtime rates under matching pay rates     |
| `POST /<recurrence_type>s/search`          | Recurrences under matching work assignments |
| `POST /<line_item_type>_line_items/search` | Line 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
* `work_assignment_ids`: array of work assignment IDs, selecting the pay stubs for those work assignments
* `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.

```json theme={null}
{
  "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`

```json theme={null}
{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": "all"
  }
}
```

### Find work assignments by payee name

`POST /work_assignments/search`

```json theme={null}
{
  "business_entity_id": "be_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "work_assignments": {
    "include": {
      "payee_names": "Smith"
    }
  }
}
```

### Find all recurring allowances tied to a specific business preset

`POST /allowances/search`

```json theme={null}
{
  "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`

```json theme={null}
{
  "payroll_id": "payrl_01J8KX9R2FMQVW3TNZH5Y7B4C6",
  "pay_stubs": {
    "include": {
      "payee_type": "contractor"
    }
  }
}
```