API Reference

Invoices

List, propose, and read invoices. Writes are propose-only — a person or BOB sends them.

GET/api/ext/v1/invoices

List invoices

Parameters

Name	In	Type	Description
status	query	string	Filter by status (draft, sent, paid, overdue, voided). Default: all.
limit	query	integer	Page size (default 50, max 200).

Responses

200Your organization's invoices, newest first. Amounts are in integer cents; bearer share links and payment-processor identifiers are never included.

200 example

[
  {
    "created_at": "2026-01-15T09:30:00Z",
    "currency": "USD",
    "description": "Design services — March 2026",
    "due_date": "2026-01-15T09:30:00Z",
    "id": "inv_8fq2Lm",
    "number": "INV-1042",
    "paid_at": "2026-01-15T09:30:00Z",
    "recipient_email": "[email protected]",
    "recipient_name": "Acme Corp",
    "sent_at": "2026-01-15T09:30:00Z",
    "status": "paid",
    "subtotal_cents": 150000,
    "tax_cents": 0,
    "total_cents": 150000,
    "updated_at": "2026-01-15T09:30:00Z",
    "voided_at": "2026-01-15T09:30:00Z"
  }
]

Errors

400Invalid limit (must be 1..200)

401Missing or invalid API token

403Token lacks the required scope or credential class

429Rate limit exceeded

All errors return { "error": string }.

Example request

curl https://api.bankofbots.ai/api/ext/v1/invoices \
  -H "Authorization: Bearer $BOB_API_TOKEN"

POST/api/ext/v1/invoices

Propose an invoice

Request body

Field	Type	Description
currencyrequired	string	ISO currency code (USD only).
descriptionrequired	string	Invoice description / memo.
due_dateoptional	string · nullable	Due date (YYYY-MM-DD). Optional.
line_itemsrequired	CreateInvoiceLineItem[]	One or more line items.
notesrequired	string	Optional internal notes.
recipient_emailrequired	string	Recipient email address.
recipient_namerequired	string	Who to bill.

Responses

201The drafted invoice. PROPOSE-ONLY: it lands as a draft under your organization and is never sent or charged by this call — a person or BOB sends it. Amounts in integer cents.

Field	Type	Description
created_atrequired	string · date-time	When the invoice was created.
currencyrequired	string	ISO currency code (USD).
descriptionrequired	string	Free-text description / memo.
due_dateoptional	string · date-time	When payment is due. Null if unset.
idrequired	string	The invoice id.
numberrequired	string	Human-readable invoice number (e.g. INV-1042).
paid_atoptional	string · date-time	When the invoice was paid in full. Null if unpaid.
recipient_emailrequired	string	Recipient email address.
recipient_namerequired	string	Who the invoice is billed to.
sent_atoptional	string · date-time	When the invoice was sent. Null if still a draft.
statusrequired	string	draft, sent, paid, overdue, or voided.
subtotal_centsrequired	int64	Line-item subtotal, in cents.
tax_centsrequired	int64	Tax amount, in cents.
total_centsrequired	int64	Total due, in cents.
updated_atrequired	string · date-time	When the invoice was last updated.
voided_atoptional	string · date-time	When the invoice was voided. Null if not voided.

201 example

{
  "created_at": "2026-01-15T09:30:00Z",
  "currency": "USD",
  "description": "Design services — March 2026",
  "due_date": "2026-01-15T09:30:00Z",
  "id": "inv_8fq2Lm",
  "number": "INV-1042",
  "paid_at": "2026-01-15T09:30:00Z",
  "recipient_email": "[email protected]",
  "recipient_name": "Acme Corp",
  "sent_at": "2026-01-15T09:30:00Z",
  "status": "paid",
  "subtotal_cents": 150000,
  "tax_cents": 0,
  "total_cents": 150000,
  "updated_at": "2026-01-15T09:30:00Z",
  "voided_at": "2026-01-15T09:30:00Z"
}

Errors

400Invalid body, due_date, or a non-positive line item amount

401Missing or invalid API token

403Token lacks the required scope or credential class

409Your organization has no active owner to attribute the invoice to

422Unsupported currency (USD only)

429Rate limit exceeded

All errors return { "error": string }.

Example request

curl -X POST https://api.bankofbots.ai/api/ext/v1/invoices \
  -H "Authorization: Bearer $BOB_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "description": "Design services — March 2026",
    "due_date": "2026-02-14",
    "line_items": [
      {
        "description": "Brand identity design",
        "quantity": "1",
        "unit_price_cents": 150000
      }
    ],
    "notes": "Net 30.",
    "recipient_email": "[email protected]",
    "recipient_name": "Acme Corp"
  }'

GET/api/ext/v1/invoices/{invoiceId}

Get an invoice

Parameters

Name	In	Type	Description
invoiceIdrequired	path	string	The invoice's id.

Responses

200The invoice. Amounts in integer cents; no share link or processor ids.

Field	Type	Description
created_atrequired	string · date-time	When the invoice was created.
currencyrequired	string	ISO currency code (USD).
descriptionrequired	string	Free-text description / memo.
due_dateoptional	string · date-time	When payment is due. Null if unset.
idrequired	string	The invoice id.
numberrequired	string	Human-readable invoice number (e.g. INV-1042).
paid_atoptional	string · date-time	When the invoice was paid in full. Null if unpaid.
recipient_emailrequired	string	Recipient email address.
recipient_namerequired	string	Who the invoice is billed to.
sent_atoptional	string · date-time	When the invoice was sent. Null if still a draft.
statusrequired	string	draft, sent, paid, overdue, or voided.
subtotal_centsrequired	int64	Line-item subtotal, in cents.
tax_centsrequired	int64	Tax amount, in cents.
total_centsrequired	int64	Total due, in cents.
updated_atrequired	string · date-time	When the invoice was last updated.
voided_atoptional	string · date-time	When the invoice was voided. Null if not voided.

200 example

{
  "created_at": "2026-01-15T09:30:00Z",
  "currency": "USD",
  "description": "Design services — March 2026",
  "due_date": "2026-01-15T09:30:00Z",
  "id": "inv_8fq2Lm",
  "number": "INV-1042",
  "paid_at": "2026-01-15T09:30:00Z",
  "recipient_email": "[email protected]",
  "recipient_name": "Acme Corp",
  "sent_at": "2026-01-15T09:30:00Z",
  "status": "paid",
  "subtotal_cents": 150000,
  "tax_cents": 0,
  "total_cents": 150000,
  "updated_at": "2026-01-15T09:30:00Z",
  "voided_at": "2026-01-15T09:30:00Z"
}

Errors

401Missing or invalid API token

403Token lacks the required scope or credential class

404No such invoice in your organization

429Rate limit exceeded

All errors return { "error": string }.

Example request

curl https://api.bankofbots.ai/api/ext/v1/invoices/{invoiceId} \
  -H "Authorization: Bearer $BOB_API_TOKEN"

GET/api/ext/v1/invoices/{invoiceId}/pdf

Download an invoice PDF

Parameters

Name	In	Type	Description
invoiceIdrequired	path	string	The invoice's id.

Responses

200The rendered invoice document (USD only). Generated on demand and streamed — never stored.

Errors

401Missing or invalid API token

403Token lacks the required scope or credential class

404No such invoice in your organization

422The invoice cannot be rendered as a PDF (non-USD, or content withheld)

429Rate limit exceeded

All errors return { "error": string }.

Example request

curl https://api.bankofbots.ai/api/ext/v1/invoices/{invoiceId}/pdf \
  -H "Authorization: Bearer $BOB_API_TOKEN"

Was this page helpful?