Mandate Search & Filter API

The Mandate Search & Filter API is a tRPC procedure that allows you to search and filter across all mandates in the system. It is used by the agentOS dashboard and is available for any consuming application performing mandate lookups via the API.

Overview

Full-text search across tenant name and email
Multi-facet filtering by status, amount, collection day, creation date, and clawback presence
Cursor-based pagination for efficient, consistent traversal of large result sets

Search

You can search mandates by free text. The search matches against:

Field	Description
`tenant_name`	The full name of the tenant
`tenant_email`	The email address of the tenant

Partial matches are supported.

Filters

Filters can be combined with search or used independently. All filters are optional.

`status`

Filter mandates by their current lifecycle status.

Value	Description
`active`	Mandate is live and collections are running
`suspended`	Mandate has been temporarily suspended
`cancelled`	Mandate has been cancelled
`failed`	Mandate setup or collection has failed

{ "status": "active" }

`amount_range`

Filter by the mandate's collection amount. Accepts a min and/or max value in pence (GBP).

{ "amount_range": { "min": 50000, "max": 150000 } }

`collection_day`

Filter by the day of the month on which the collection is scheduled to run.

{ "collection_day": 1 }

`date_created_range`

Filter mandates created within a given date window. Accepts ISO 8601 date strings.

{
  "date_created_range": {
    "from": "2024-01-01",
    "to": "2024-06-30"
  }
}

`has_clawback`

Boolean filter. When true, returns only mandates that currently have an active clawback recorded.

{ "has_clawback": true }

Pagination

Results are returned using cursor-based pagination. This approach is stable and efficient for large datasets — it does not suffer from the offset drift problem when records are inserted or updated between pages.

Request

Parameter	Type	Description
`cursor`	`string` \| `undefined`	The cursor returned by the previous page. Omit on the first request.
`limit`	`number`	Number of results per page.

Response

Field	Type	Description
`items`	`Mandate[]`	The mandates matching the query for this page.
`nextCursor`	`string` \| `null`	Cursor to pass in the next request. `null` indicates the final page.

Example — First Page

{
  "search": "Jane",
  "status": "active",
  "limit": 20
}

Example — Subsequent Page

{
  "search": "Jane",
  "status": "active",
  "limit": 20,
  "cursor": "eyJpZCI6ImFiYzEyMyJ9"
}

Usage Notes

All filters are additive (AND logic) — results must satisfy every filter supplied.
Search and filters can be combined freely.
This procedure is consumed by both the agentOS dashboard (mandate lookup) and direct API integrations.
Results are scoped per customer — a consumer will only ever see mandates belonging to their own account.