---
title: "Attach documents to a bill"
method: POST
path: "/v2/bills/{billId}/documents"
---

# Attach documents to a bill

`POST /v2/bills/{billId}/documents`

## Request

- Base URL: `https://api.slash.com`
- URL: `https://api.slash.com/v2/bills/{billId}/documents`
- Auth: API key in header `X-API-Key`

Attach uploaded documents to a bill. Documents already on the bill are ignored.

## Request body

- object
  - `documentIds` string[], required: Documents uploaded with purpose `bill_invoice`.

## Response `200`

The bill with the documents attached.

- Bill: Money your legal entity owes a vendor. `status` and `amounts.outstanding` are derived from the bill's payments and cannot be set directly.
  - `id` string, required: Bill id with the `bill_` prefix.
  - `status` 'draft' | 'pending_approval' | 'rejected' | 'scheduled' | 'payment_pending' | 'paid' | 'payment_failed' | 'partially_paid', required: Derived from the bill's payments. `draft` until a payment exists; `pending_approval` while a payment awaits approval; `rejected` when the latest approval was rejected; `scheduled` when a payment is scheduled; `payment_pending` while a payment is in flight; `partially_paid` when settled payments cover part of the total; `paid` when they cover all of it; `payment_failed` when the latest payment failed or was returned.
  - `source` 'manual' | 'email' | 'carrier_account' | 'api', required: How the bill entered Slash. `api` for bills created through this API, `manual` for the dashboard, `email` for the accounts-payable inbox, `carrier_account` for bills pulled from a connected carrier portal. Carrier bills are read-only over the API.
  - `recipientId` string: The vendor, a recipient readable at `GET /v2/recipients/{recipientId}`.
  - `destinationId` string: The destination the bill is expected to be paid to, readable at `GET /v2/destinations/{destinationId}`.
  - `ownerUserId` string: The user responsible for the bill. Absent for bills that arrived by email and have not been assigned.
  - `invoiceNumber` string: The vendor's invoice number.
  - `invoiceDate` string, date: Invoice date as `YYYY-MM-DD`.
  - `dueDate` string, date: Due date as `YYYY-MM-DD`.
  - `currency` string, required: Uppercase ISO 4217 currency code shared by every amount on the bill.
  - `amounts` object, required: Every amount is in `currency`, in minor units.
    - `total` Money, required: A signed monetary amount expressed in minor units.
      - `amount` integer, required: Amount in the currency's minor units.
      - `currency` string, required: Uppercase ISO 4217 currency code.
    - `tax` Money, required: A signed monetary amount expressed in minor units.
      - `amount` integer, required: Amount in the currency's minor units.
      - `currency` string, required: Uppercase ISO 4217 currency code.
    - `discount` Money, required: A signed monetary amount expressed in minor units.
      - `amount` integer, required: Amount in the currency's minor units.
      - `currency` string, required: Uppercase ISO 4217 currency code.
    - `outstanding` Money, required: A signed monetary amount expressed in minor units.
      - `amount` integer, required: Amount in the currency's minor units.
      - `currency` string, required: Uppercase ISO 4217 currency code.
  - `lineItems` BillLineItem[], required: Line items in display order.
    - `id` string, required: Line item id with the `bill_line_item_` prefix.
    - `name` string, required: What the line is for, as printed on the invoice.
    - `quantity` number, required: Number of units. Fractional quantities are allowed.
    - `unitAmount` Money, required: A signed monetary amount expressed in minor units.
      - `amount` integer, required: Amount in the currency's minor units.
      - `currency` string, required: Uppercase ISO 4217 currency code.
    - `total` Money, required: A signed monetary amount expressed in minor units.
      - `amount` integer, required: Amount in the currency's minor units.
      - `currency` string, required: Uppercase ISO 4217 currency code.
  - `documentIds` string[], required: Documents attached to the bill, readable at `GET /v2/documents/{documentId}`.
  - `payments` BillPayment[], required: Payments linked to the bill, oldest first.
    - `id` string, required: Payment link id with the `bill_payment_` prefix. Unlink the payment with `DELETE /v2/bills/{billId}/payments/{paymentId}`.
    - `transferId` string: Id of the transfer that pays the bill, with the `transfer_intent_` prefix, readable at `GET /v2/transfers/{transferId}`. Absent for payments that are not yet a transfer (a scheduled payment whose transfer has not been constructed) or that were made outside the transfer rails.
    - `transactionId` string: Id of the transaction that moved the money, with the `agg_tx_` prefix, readable at `GET /v2/transactions/{transactionId}`. For a card purchase it's the card transaction. Absent when the payment's only transactions are ones the transactions API doesn't return, such as a rejected or canceled approval request.
    - `status` 'pending' | 'posted' | 'failed', required: Coarse transaction state.
    - `detailedStatus` 'pending' | 'pending_destination' | 'pending_approval' | 'in_review' | 'scheduled' | 'canceled' | 'failed' | 'settled' | 'declined' | 'refund' | 'reversed' | 'returned' | 'dispute', required: Exact transaction lifecycle state across every category.
    - `amount` Money, required: A signed monetary amount expressed in minor units.
      - `amount` integer, required: Amount in the currency's minor units.
      - `currency` string, required: Uppercase ISO 4217 currency code.
    - `createdAt` string, date-time, required: When the payment was linked to the bill.
  - `notes` string: Free-text notes visible to your organization.
  - `createdAt` string, date-time, required: When the bill was created.

## Other responses

- `400`: - `document_purpose_mismatch` — The document was uploaded with a different `purpose`. - `invalid_request (request shape)` — The body, query, or headers failed validation, or a required header is missing. `details` has one entry per failing location, keyed by JSON pointer or header name.
- `401`: - `unauthorized` — API key authentication is missing or invalid.
- `403`: - `forbidden` — The credential is not permitted to perform this action on the resource. When the resource is a field of the request, `details` names that `field` and the `id` it received. - `forbidden (legal entity)` — The credential is not permitted to act for the selected legal entity. - `not_available` — Public API v2 is not yet available. Use [Public API v1](https://docs.slash.com/introduction) in the meantime. - `user_api_key_required` — The API key is scoped to a legal entity rather than a user. Every v2 request needs a user API key, created under Settings → API keys in the Slash dashboard, together with the `x-legal-entity` header.
- `404`: - `not_found` — No resource matches the identifier. When the identifier is a field of the request, `details` names that `field` and the `id` it received.
- `409`: - `carrier_bill_read_only` — The bill was pulled from a connected carrier portal and is managed by that connection. It can be read but not changed.
- `429`: The request exceeded the applicable rate limit. The response body is plain text, not the error object; clients must not depend on its wording.
- `500`: - `internal` — Slash could not complete the request. Quote `referenceId` when contacting Slash support.

## Changes

- **2026-10-16** `8b5d371ffeea`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/slashfi/apis/slash-public-api/changes/v2/bills/:billId/documents/post.md)

---

[API](https://skmtc.dev/slashfi/apis/slash-public-api.md) - [All operations](https://skmtc.dev/slashfi/apis/slash-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/slashfi/apis/slash-public-api/revisions/eaed2d63c9e2?raw)