v1.0.90: Full API Documentation & Developer Reference Now Available

With the release of v1.0.90, the Direct Debit Collection Service now ships a comprehensive, hosted API reference covering every public endpoint. Whether you're integrating from agentOS or building a new consumer on top of the service, everything you need to get started is now in one place at /docs.

What's Covered

Authentication

All API requests are authenticated using an API key passed in the request header. The documentation includes:

The exact header format required
How to obtain and rotate API keys
Error codes returned for invalid, expired, or missing credentials

Authorization: Bearer <your-api-key>

Mandate Invite Creation

POST /mandates/invite

Send a Direct Debit mandate invitation to a tenant. The endpoint generates a unique, token-based mandate form link and dispatches it to the tenant.

Documented fields include the tenant's contact details, the collection amount and frequency, and the intended collection date. Example request and response payloads are included.

Mandate Status Retrieval

GET /mandates/{id}

Retrieve the current state of a mandate. The reference covers all possible mandate states — such as pending, active, suspended, cancelled, and failed — and describes what each state means in the context of the BACS/AUDDIS lifecycle.

Collection Listing

GET /collections

List collections associated with a mandate or across a customer account. The documentation covers available filter parameters (date range, status, mandate ID) and pagination behaviour.

Alert Listing & Acknowledgement

GET /alerts · POST /alerts/{id}/acknowledge

Retrieve active alerts raised by the service's threshold monitoring (e.g. high mandate creation rate, collection volume breaches, clawback reserve warnings) and acknowledge them once reviewed. Example payloads for both endpoints are included.

Gatekeeping Status

The gatekeeping endpoint allows a consuming application to check whether a tenant's mandate is in a state that should restrict their access. The documentation describes the response contract and how to interpret the status flags.

Webhook Event Catalogue

The service emits webhook events throughout the Direct Debit lifecycle. The new catalogue documents:

Every event type (e.g. mandate activated, collection submitted, collection failed, clawback received)
The full schema for each event payload
Annotated example payloads
Delivery behaviour: retry logic, ordering guarantees, and failure handling

Where to Find It

The API reference is hosted as a static page at:

/docs

No authentication is required to access the documentation. All example payloads use realistic, anonymised data.

No Breaking Changes

This is a documentation-only release. No changes were made to the API itself. Existing integrations are unaffected.