# Billers API

Search the biller directory and retrieve a single biller.

> **Scope of this file.** It is the OPERATION reference for THIS resource, generated from the BillerAPI OpenAPI document served at [/docs/openapi.json](/docs/openapi.json): each API-key endpoint the resource owns, with its parameters, request body, responses and schemas. Narrative and catalog sections the rendered page also carries (walkthroughs, event taxonomies, payload catalogs) are NOT reproduced here — read [/docs/api/billers](/docs/api/billers) for those. Endpoints the hosted flow drives from inside the iframe, and dashboard-session endpoints, are absent by design: they are not API-key operations. [/docs/api.md](/docs/api.md) enumerates the full API-key surface, including the endpoints that have no reference page yet.

All request and response field names are snake_case. Errors use the coded envelope described in [/docs/concepts/errors.md](/docs/concepts/errors.md).

## Endpoints

- [`GET /v1/billers`](#get-v1billers)
- [`GET /v1/billers/search/by-email`](#get-v1billerssearchby-email)
- [`GET /v1/billers/{id}`](#get-v1billersid)

## GET /v1/billers

List billers

Retrieve list of available billers with optional filtering. Requires client credentials.

Operation ID: `listBillers`

Auth: `client-api-key`

**Parameters**

| Parameter | In | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- | --- |
| `search_term` | query | no | string | — | — |
| `status` | query | no | string | — | — |
| `type` | query | no | string | — | — |
| `consent_scope` | query | no | string | — | — |
| `limit` | query | no | number | default `100`; minimum `1`; maximum `500` | Maximum number of billers to return (1–500, default 100). |
| `cursor` | query | no | string | — | Opaque pagination cursor from a prior response’s `next_cursor`. Omit for the first page; the response always returns `next_cursor` / `has_more`. |
| `sort_by` | query | no | string | — | — |
| `sort_order` | query | no | string | — | — |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | List of billers | — |

## GET /v1/billers/search/by-email

Search billers by email domain

Find billers matching an email domain

Operation ID: `searchBillersByEmail`

Auth: `client-api-key`

**Parameters**

| Parameter | In | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- | --- |
| `email` | query | yes | string | — | — |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | Matching billers | — |

## GET /v1/billers/{id}

Get biller by id (global catalog)

Returns the biller catalog entry (name, type, status, capability flags). Authenticated portal users may view any catalog biller; per-client scoping lives in the activity feed, not the entity itself. 404 if unknown id.

Operation ID: `getById`

Auth: `client-api-key`

**Parameters**

| Parameter | In | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- | --- |
| `id` | path | yes | string | — | — |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | Biller entity. | — |
| 401 | No portal session (NEEDS_RESIGNIN). | — |
| 404 | Biller not found (BILLER_NOT_FOUND). | — |

## See also

- [API reference index](/docs/api.md)
- [Authentication](/docs/guides/authentication.md)
- [Pagination](/docs/concepts/pagination.md)
- [Error handling](/docs/concepts/errors.md)