All Docs
FeaturesagentOS Direct DebitUpdated March 20, 2026

Mandate Search & Bulk Actions

Mandate Search & Bulk Actions

Available from v1.0.89

This release introduces mandate search and bulk action capabilities, giving agents the tools to quickly find and manage groups of mandates — especially useful at critical points in a tenancy lifecycle such as end-of-tenancy portfolio transitions.

Searching Mandates

The mandate search allows agents (or API consumers) to locate mandates using any of the following fields:

FieldDescription
tenant_nameFull or partial tenant name
emailTenant email address
sort_code_last4Last 4 digits of the tenant's sort code
property_referenceThe property reference associated with the mandate
modulr_mandate_referenceThe Modulr-assigned mandate reference

Notes on Sort Code Search

Only the last 4 digits of the sort code are used for search. This is intentional — it avoids exposing full bank details in search queries while still allowing agents to differentiate between accounts.

Bulk Actions

Once mandates are located (via search or list), multiple mandates can be selected and a single bulk action applied across all of them.

Supported Actions

Suspend

Suspends all selected active mandates. No further collections will be attempted until the mandate is reactivated. Useful when a property becomes vacant and collections should be paused immediately.

Cancel

Permanently cancels all selected mandates. This action is irreversible — a new mandate setup flow is required to reinstate collection for any affected tenant.

Send Reminder Emails

Dispatches a reminder email to the tenant associated with each selected mandate. Useful for prompting tenants to complete an incomplete mandate setup or to remind them of an upcoming collection.

End-of-Tenancy Use Case

A common scenario is managing an entire property portfolio at end of tenancy:

  1. Search mandates by property_reference to pull up all tenants at a given property or across a portfolio.
  2. Select all returned mandates.
  3. Apply Cancel or Suspend as a bulk action.

All selected mandates are processed in a single operation without the agent having to action each one individually.

How Bulk Actions Are Processed

Bulk actions are not processed synchronously. When a bulk action is submitted, each mandate action is queued as an individual Inngest event. This approach:

  • Prevents hitting Modulr API rate limits when acting on large sets of mandates
  • Ensures each action is retried independently if a transient error occurs
  • Keeps the API response fast regardless of the number of mandates selected

What This Means in Practice

  • The API will return a 202 Accepted response immediately upon receiving a valid bulk action request.
  • Mandate statuses will update asynchronously as Inngest processes each queued event.
  • Agents should allow a short processing window before expecting all statuses to reflect the bulk action, particularly for very large selections.

Related