# Search Payroll Template

`POST /accounting/payroll-templates/search`

Group: Accounting › Payroll Templates · Operation ID: `searchPayrollTemplate`

Returns the payroll templates that match the given filters, each including its categories.

All filters are optional and are combined with AND. Omit every filter to match all payroll templates. Lookup by name lives here because a path takes only the id, and entityId lives here because a template is mapped to entities through a join, not a column.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=searchPayrollTemplate)

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | `"v1"` | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |

## Request body

Required, `application/json`: searchPayrollTemplateInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | object | no | The filters to apply. A template must match every filter you send. Omit to return all payroll templates. |
| `filters.id` | string | no | Limits results to the template with this identifier. |
| `filters.name` | string | no | Limits results to the template with this exact name. The name is unique across payroll templates, so this returns at most one template. |
| `filters.groupBy` | string | no | Limits results to templates that enter amounts at this level. One of 'Employee', 'Department' or 'Multi-level'. Any other value matches no template. |
| `filters.status` | string | no | Limits results to templates in this lifecycle status. One of 'create', 'active', 'inactive'. Any other value matches no template. |
| `filters.source` | string | no | Limits results to templates importing from this payroll system. Accepted values: 'datev', 'datevEmployeePayroll', 'datevEmployeePayrollPersonLevel', 'rippling', 'lexware', 'briars', 'gusto', 'adpGLReport', 'adpPayrollHistory', 'sage', 'none'. Any other value matches no template. |
| `filters.journalEntryGroupBy` | string | no | Limits results to templates with this default journal consolidation level. One of 'account', 'accountAndPayrollCategory', 'payrollCategory' or 'payrollCategoryByEmployee'. Any other value matches no template. |
| `filters.entityId` | string | no | Limits results to templates mapped to this legal entity. An id that matches no entity returns no template. See id on GET base/entities. |
| `page` | object | no | Pagination controls. Omit for the first page. |
| `page.cursor` | string | no | The cursor from the previous response's pagination.nextCursor. Omit for the first page. |
| `page.size` | number | no | The number of payroll templates per page. Defaults to 50. A value above 200 is treated as 200, not rejected. |

Example:

```json
{
  "filters": {
    "status": "active"
  },
  "page": {
    "size": 50
  }
}
```

## Response

`200` Success

Under `data` (searchPayrollTemplateOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | yes | The payroll templates on this page, most recently created first. An empty array when nothing matches. |
| `items[].id` | string | yes | The unique identifier for the payroll template. |
| `items[].name` | string | yes | The name of the payroll template. Unique across payroll templates. |
| `items[].description` | string | no | A free-form description of the payroll template. |
| `items[].groupBy` | string | yes | The level at which payroll amounts are entered. One of 'Employee', 'Department' or 'Multi-level'. |
| `items[].journalEntryDate` | string | yes | The date the generated journal entry is posted on. Possible values: 'payrollDate', 'endDate'. |
| `items[].journalEntryGroupBy` | string | yes | The default consolidation level for generated journal lines. One of 'account', 'accountAndPayrollCategory', 'payrollCategory' or 'payrollCategoryByEmployee'. |
| `items[].deductionsType` | string | yes | Whether deduction amounts in imported data arrive positive or negative. Possible values: 'positive', 'negative'. |
| `items[].source` | string | no | The payroll system this template imports from. Possible values: 'datev', 'datevEmployeePayroll', 'datevEmployeePayrollPersonLevel', 'rippling', 'lexware', 'briars', 'gusto', 'adpGLReport', 'adpPayrollHistory', 'sage', 'none'. |
| `items[].status` | string | no | The lifecycle status of the payroll template. One of 'create', 'active', 'inactive'. It is computed from the template's categories, not set through the API. |
| `items[].clearingAccountId` | string | no | The GL account payroll amounts are cleared through. See id on GET accounting/accounts/:id. |
| `items[].entities` | array of string | yes | The names of the legal entities this template is mapped to. An empty array when it is mapped to none. |
| `items[].lastModifiedDate` | string (date-time) | yes | The date and time the payroll template last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `items[].categories` | array of object | no | The payroll categories defined on this template, each mapping one payroll line type onto a debit and a credit account. An empty array when the template has none. |
| `items[].categories[].id` | string | yes | The unique identifier for the payroll category. |
| `items[].categories[].name` | string | yes | The name of the category, for example 'Gross Salary'. Unique within the template. |
| `items[].categories[].subType` | string | yes | The kind of payroll amount this category represents. One of 'grossPay', 'deduction', 'netPay' or 'employer'. |
| `items[].categories[].status` | string | no | The lifecycle status of the category. One of 'active' or 'inactive'. |
| `items[].categories[].payee` | string | no | Who the amount is paid to, as a payee code from your tenant's configured payee list, for example 'employee', 'payrollProvider', 'benefitsProvider' or 'taxOffice'. |
| `items[].categories[].isManagedFromPayroll` | boolean | no | Whether payments for this category are recorded through payroll rather than separately. |
| `items[].categories[].debitAccountId` | string | no | The GL account this category debits. See id on GET accounting/accounts/:id. |
| `items[].categories[].debitJournalAggregation` | string | no | The consolidation level for journal lines posted to the debit account. Absent means the template default applies. |
| `items[].categories[].creditAccountId` | string | no | The GL account this category credits. See id on GET accounting/accounts/:id. |
| `items[].categories[].creditJournalAggregation` | string | no | The consolidation level for journal lines posted to the credit account. Absent means the template default applies. |
| `pagination` | object | yes | The pagination cursor for this page. |
| `pagination.nextCursor` | string | no | The cursor for the next page. Pass it as page.cursor. Absent on the last page. |
| `pagination.hasMore` | boolean | yes | True when more matches remain beyond this page. |

## Statuses

- `400` — Invalid request or business failure
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `429` — Too many requests
- `500` — Internal server error