# Request to Link API

Biller-initiated link requests and their lifecycle.

> **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/request-to-link](/docs/api/request-to-link) 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/request-to-links`](#get-v1request-to-links)
- [`POST /v1/request-to-links`](#post-v1request-to-links)
- [`GET /v1/request-to-links/{id}`](#get-v1request-to-linksid)
- [`PATCH /v1/request-to-links/{id}/status`](#patch-v1request-to-linksidstatus)
- [`POST /v1/request-to-links/{id}/cancel`](#post-v1request-to-linksidcancel)
- [`POST /v1/request-to-links/{id}/proceed`](#post-v1request-to-linksidproceed)

## GET /v1/request-to-links

List request-to-link records for the calling client

Operation ID: `list`

Auth: `client-api-key`

**Parameters**

| Parameter | In | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- | --- |
| `limit` | query | no | number | — | Page size (1–200, default 50). |
| `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`. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | List of request-to-link records | — |

## POST /v1/request-to-links

Create a request-to-link resource

Operation ID: `create`

Auth: `client-api-key`

**Request body** (required)

Schema: `CreateRequestToLinkDto`

| Field | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `client_id` | no | string | — | Optional client tenant id. When supplied, it must match the authenticated client. |
| `client_user_id` | yes | string | — | Your end-user identifier — opaque to BillerAPI; ties an RTL to one user in your system. |
| `biller_id` | no | string | — | Existing biller id from GET /v1/billers. Supply exactly one of biller_id or onboarding. |
| `onboarding` | no | RequestToLinkOnboardingDto | — | Explicit request for BillerAPI to onboard a biller that is not in the catalog. Supply exactly one of biller_id or onboarding. |
| `consents` | no | array<string> | — | Consent scopes the end user is granting for the resulting link session. |
| `metadata` | no | object | open object (extra keys allowed) | Arbitrary client-supplied metadata, echoed back on GET. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 201 | — | — |

## GET /v1/request-to-links/{id}

Get request-to-link details

Operation ID: `getById`

Auth: `client-api-key`

**Parameters**

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

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | Request-to-link details | — |
| 404 | Request-to-link not found | — |

## PATCH /v1/request-to-links/{id}/status

Update request-to-link status

Operation ID: `updateStatus`

Auth: `client-api-key`

**Parameters**

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

**Request body** (required)

Schema: `UpdateRequestToLinkStatusDto`

> The OpenAPI document declares this body but does not describe its fields, so this file cannot list them and will not guess. Read [/docs/api/request-to-link](/docs/api/request-to-link) for the fields this endpoint expects.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | — | — |

## POST /v1/request-to-links/{id}/cancel

Cancel request-to-link

Operation ID: `cancel`

Auth: `client-api-key`

**Parameters**

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

**Request body** (required)

Schema: `CancelRequestToLinkDto`

> The OpenAPI document declares this body but does not describe its fields, so this file cannot list them and will not guess. Read [/docs/api/request-to-link](/docs/api/request-to-link) for the fields this endpoint expects.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 201 | — | — |

## POST /v1/request-to-links/{id}/proceed

Proceed request-to-link to link session

Operation ID: `proceed`

Auth: `client-api-key`

**Parameters**

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

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 201 | — | — |

## Schemas

### CancelRequestToLinkDto

No object properties are declared for this schema in the OpenAPI document.

### CreateRequestToLinkDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `client_id` | no | string | — | Optional client tenant id. When supplied, it must match the authenticated client. |
| `client_user_id` | yes | string | — | Your end-user identifier — opaque to BillerAPI; ties an RTL to one user in your system. |
| `biller_id` | no | string | — | Existing biller id from GET /v1/billers. Supply exactly one of biller_id or onboarding. |
| `onboarding` | no | RequestToLinkOnboardingDto | — | Explicit request for BillerAPI to onboard a biller that is not in the catalog. Supply exactly one of biller_id or onboarding. |
| `consents` | no | array<string> | — | Consent scopes the end user is granting for the resulting link session. |
| `metadata` | no | object | open object (extra keys allowed) | Arbitrary client-supplied metadata, echoed back on GET. |

### RequestToLinkOnboardingDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `biller_name` | yes | string | — | Display name supplied by the end user. BillerAPI preserves this value exactly when creating the biller. |
| `biller_url` | yes | string | — | HTTPS login or account URL for the biller. BillerAPI validates DNS/IP safety and canonicalizes the URL server-side. |

### UpdateRequestToLinkStatusDto

No object properties are declared for this schema in the OpenAPI document.


## See also

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