# Bill Imports API

Upload, review, and commit a bill document for an unlinked account.

> **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/bill-imports](/docs/api/bill-imports) 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

- [`POST /v1/bill_imports`](#post-v1bill_imports)
- [`POST /v1/bill_imports/{id}/complete_upload`](#post-v1bill_importsidcomplete_upload)
- [`GET /v1/bill_imports/{id}`](#get-v1bill_importsid)
- [`DELETE /v1/bill_imports/{id}`](#delete-v1bill_importsid)
- [`GET /v1/bill_imports/{id}/source_document`](#get-v1bill_importsidsource_document)
- [`PATCH /v1/bill_imports/{id}/review_draft`](#patch-v1bill_importsidreview_draft)
- [`POST /v1/bill_imports/{id}/confirm`](#post-v1bill_importsidconfirm)

## POST /v1/bill_imports

Create a bill import and direct-upload target

Operation ID: `create`

Auth: `client-api-key`

**Parameters**

| Parameter | In | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- | --- |
| `idempotency-key` | header | yes | string | — | — |

**Request body** (required)

Schema: `CreateBillImportDto`

> 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/bill-imports](/docs/api/bill-imports) for the fields this endpoint expects.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 201 | Import and presigned upload target created. | — |

## POST /v1/bill_imports/{id}/complete_upload

Verify the immutable upload and start processing

Operation ID: `completeUpload`

Auth: `client-api-key`

**Parameters**

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

**Request body** (required)

Schema: `CompleteBillImportUploadDto`

> 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/bill-imports](/docs/api/bill-imports) for the fields this endpoint expects.

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 202 | Upload accepted for asynchronous processing. | — |

## GET /v1/bill_imports/{id}

Retrieve a bill import

Operation ID: `retrieve`

Auth: `client-api-key`

**Parameters**

| Parameter | In | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- | --- |
| `id` | path | yes | string | — | — |
| `x-client-user-id` | header | yes | string | — | — |
| `X-Client-User-ID` | header | yes | string | — | — |

**Responses**

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

## DELETE /v1/bill_imports/{id}

Cancel an uncommitted import and schedule document deletion

Operation ID: `cancel`

Auth: `client-api-key`

**Parameters**

| Parameter | In | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- | --- |
| `id` | path | yes | string | — | — |
| `x-client-user-id` | header | yes | string | — | — |
| `X-Client-User-ID` | header | yes | string | — | — |

**Responses**

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

## GET /v1/bill_imports/{id}/source_document

Get a short-lived URL for the imported source document

Operation ID: `getSourceDocument`

Auth: `client-api-key`

**Parameters**

| Parameter | In | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- | --- |
| `id` | path | yes | string | — | — |
| `x-client-user-id` | header | yes | string | — | — |
| `X-Client-User-ID` | header | yes | string | — | — |

**Responses**

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

## PATCH /v1/bill_imports/{id}/review_draft

Conditionally update the review draft

Operation ID: `updateReviewDraft`

Auth: `client-api-key`

**Parameters**

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

**Request body** (required)

Schema: `UpdateBillImportReviewDraftDto`

| Field | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `changes` | yes | BillImportReviewChangesDto | — | — |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 409 | Draft version conflict with current draft. | — |

## POST /v1/bill_imports/{id}/confirm

Atomically commit the reviewed import to one Bill

Operation ID: `confirm`

Auth: `client-api-key`

**Parameters**

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

**Request body** (required)

Schema: `ConfirmBillImportDto`

| Field | Required | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `final_changes` | yes | BillImportReviewChangesDto | — | — |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | Import committed to a canonical Bill. | `ConfirmBillImportResponseDto` |
| 409 | Lifecycle or draft version conflict. | — |

Response body — `ConfirmBillImportResponseDto` (200)

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `outcome` | yes | string | — | — |
| `bill` | yes | PublicBillResponseDto | — | — |

## Schemas

### BillImportAmountOperationDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `operation` | yes | `set` \| `clear` | — | — |
| `value` | no | number | — | — |

### BillImportClassificationOperationDto

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

### BillImportCurrencyOperationDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `operation` | yes | `set` \| `clear` | — | — |
| `value` | no | string | — | — |

### BillImportDateOperationDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `operation` | yes | `set` \| `clear` | — | — |
| `value` | no | string | — | — |

### BillImportIsoMoneyOperationDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `operation` | yes | `set` \| `clear` | — | — |
| `value` | no | IsoMoneyInputDto | — | — |

### BillImportLineItemsOperationDto

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

### BillImportRemitToAddressOperationDto

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

### BillImportReviewChangesDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `payee_name` | no | BillImportStringOperationDto | — | — |
| `amount_due` | no | BillImportAmountOperationDto | **deprecated** | — |
| `total_amount` | no | BillImportIsoMoneyOperationDto | — | — |
| `due_date` | no | BillImportDateOperationDto | **deprecated** | — |
| `due_date_iso` | no | BillImportDateOperationDto | — | — |
| `account_number` | no | BillImportStringOperationDto | — | — |
| `reference_number` | no | BillImportStringOperationDto | — | — |
| `bill_number` | no | BillImportStringOperationDto | — | — |
| `currency` | no | BillImportCurrencyOperationDto | **deprecated** | — |
| `service_period` | no | BillImportServicePeriodOperationDto | — | — |
| `remit_to_address` | no | BillImportRemitToAddressOperationDto | — | — |
| `payment_url` | no | BillImportUrlOperationDto | — | — |
| `line_items` | no | BillImportLineItemsOperationDto | — | — |
| `payment_date` | no | BillImportDateOperationDto | — | — |
| `payment_method` | no | BillImportStringOperationDto | — | — |
| `classification_override` | no | BillImportClassificationOperationDto | — | — |
| `override_reason` | no | BillImportStringOperationDto | — | — |

### BillImportServicePeriodOperationDto

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

### BillImportStringOperationDto

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

### BillImportUrlOperationDto

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

### CompleteBillImportUploadDto

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

### ConfirmBillImportDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `final_changes` | yes | BillImportReviewChangesDto | — | — |

### ConfirmBillImportResponseDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `outcome` | yes | string | — | — |
| `bill` | yes | PublicBillResponseDto | — | — |

### CreateBillImportDto

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

### Iso20022AmountResponseDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `value` | yes | string | — | — |
| `currency` | yes | string | — | — |

### IsoMoneyInputDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `value` | yes | string | — | Decimal string using the currency minor-unit exponent. |
| `currency` | yes | string | — | ISO 4217 currency code. |

### PublicBillResponseDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `total_amount` | no | Iso20022AmountResponseDto | — | — |
| `due_date_iso` | no | string \| null | — | — |
| `amount` | yes | number | **deprecated** | Legacy major-unit amount. Use total_amount.value. |
| `currency` | yes | string | **deprecated** | Legacy currency. Use total_amount.currency. |
| `due_date` | no | string \| null | **deprecated** | Legacy due date. Use due_date_iso. |
| `id` | yes | string | — | — |

### UpdateBillImportReviewDraftDto

| Field | Always present | Type | Notes | Description |
| --- | --- | --- | --- | --- |
| `changes` | yes | BillImportReviewChangesDto | — | — |


## See also

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