DocumentsList documents

Documents

List documents

GET/v1/documents

Returns invoices, estimates, credit notes and receipts, newest first, with filters for type, status, client and dates.

Use the filters to find what needs action: status=sent,overdue lists unpaid invoices, type=estimate&status=accepted lists estimates ready to convert. Several values are comma-separated. Connectors find a document they created earlier with external_ref and source.

Each document includes its computed totals, status, number, lines and links. Results use cursor pagination. See Invoices and Document statuses.

Permission
documents.view
Type
Read-only. Changes nothing.
Auth
API key, MCP token or signed-in session
Capability
list_documents
MCP tool
list_documents
CLI
freeinvoiceautomation doc list
Available
At launch, 1 January 2027
list_documents
curl --request GET \
  --url https://api.freeinvoiceautomation.com/v1/documents \
  --header 'Authorization: Bearer <api-key>'
{
  "data": [
    {
      "id": "0193f2b4-2d1e-7a6b-9c80-1f2e3d4c5b6a",
      "business_id": "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f",
      "client_id": "0193f2a0-5b3c-7d4e-8f50-6a7b8c9d0e1f",
      "type": "invoice",
      "status": "sent",
      "number": "INV-2027-0017",
      "issue_date": "2027-02-01",
      "due_date": "2027-02-15",
      "expires_at": null,
      "currency": "USD",
      "fx_rate": "0.7900000000",
      "fx_rate_source": "ecb:2027-02-01",
      "subtotal_minor": "120000",
      "discount_minor": "0",
      "tax_minor": "0",
      "total_minor": "120000",
      "amount_paid_minor": "0",
      "amount_credited_minor": "0",
      "balance_minor": "120000",
      "terms": "Payment due within 14 days.",
      "notes": "Thank you for your business.",
      "accepted_methods": [
        "0193f29f-55aa-7b66-8c77-9d88e99f0a01",
        "0193f29f-55aa-7b66-8c77-9d88e99f0a02"
      ],
      "pdf_template_id": null,
      "late_fees_enabled": false,
      "reminder_sequence_id": null,
      "promise_to_pay_date": null,
      "recurring_schedule_id": null,
      "current_version": 1,
      "first_sent_at": "2027-02-01T10:15:00Z",
      "last_sent_at": "2027-02-01T10:15:00Z",
      "accepted_at": null,
      "paid_at": null,
      "overdue_at": null,
      "voided_at": null,
      "voided_by": null,
      "void_reason": null,
      "source": "api",
      "external_ref": null,
      "client_generated_id": null,
      "lines": [
        {
          "id": "0193f2b4-2d20-7b11-8c01-0a1b2c3d4e01",
          "position": 1,
          "kind": "item",
          "item_id": "0193f2a1-7c4e-7b9a-9f10-3c2d1e0a4b51",
          "description": "Logo design",
          "quantity": "1",
          "unit": "piece",
          "unit_price_minor": "45000",
          "discount_type": null,
          "discount_value": null,
          "tax_rate_id": null,
          "tax_name": null,
          "tax_rate": null,
          "tax_calculation": null,
          "subtotal_minor": "45000",
          "tax_minor": "0",
          "total_minor": "45000",
          "credited_line_id": null
        },
        {
          "id": "0193f2b4-2d20-7b11-8c01-0a1b2c3d4e02",
          "position": 2,
          "kind": "item",
          "item_id": null,
          "description": "Brand guidelines, 12 pages",
          "quantity": "1",
          "unit": null,
          "unit_price_minor": "75000",
          "discount_type": null,
          "discount_value": null,
          "tax_rate_id": null,
          "tax_name": null,
          "tax_rate": null,
          "tax_calculation": null,
          "subtotal_minor": "75000",
          "tax_minor": "0",
          "total_minor": "75000",
          "credited_line_id": null
        }
      ],
      "links": [],
      "pay_url": "https://freeinvoiceautomation.com/pay/q7Xc2mVb9T0kRZ4aNf8sLwE1yHdPu3gJoK6iBt5nM2c",
      "created_at": "2027-02-01T09:12:44Z",
      "updated_at": "2027-02-01T10:15:00Z"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNy0wMi0wMVQxMDoxNTowMFoifQ",
  "has_more": true
}

Authorizations

Authorizationstringrequired
Bearer <api-key>. An API key from Settings > API keys, or an MCP token. See Authentication.

Query Parameters

business_idstring<uuid>
Only documents of this business. May be left out when you can reach exactly one business.
typestring
Document type, or several comma-separated.

Available options: invoice, estimate, credit_note, receipt

statusstring
Status, or several comma-separated, e.g. sent,overdue.

Available options: draft, sent, partially_paid, paid, overdue, void, changes_requested, accepted, expired, converted, issued, applied, refunded

client_idstring<uuid>
Only documents for this client.
currencystring
Only documents in this currency.
issued_afterstring<date>
Issue date on or after this day.
issued_beforestring<date>
Issue date on or before this day.
due_afterstring<date>
Due date on or after this day.
due_beforestring<date>
Due date on or before this day.
updated_afterstring<date-time>
Only documents changed after this time, for syncing.
external_refstring
Only the document with this reference.
sourcestring
Only documents from this source, e.g. woocommerce.
qstring
Text search over number and client name or email.
sortstringdefault:-created_at
Sort field; a leading - sorts descending.

Available options: created_at, -created_at, issue_date, -issue_date, due_date, -due_date, total_minor, -total_minor

limitintegerdefault:50
Page size, 1 to 200.
cursorstring
Cursor from the previous page's next_cursor.

Response

200 - application/json
dataobject[]
The documents on this page.
next_cursorstring | null
Cursor for the next page, or null on the last page.
has_moreboolean
Whether another page exists.

Errors

business_out_of_scope

Plus the common errors every call can return. See Errors.

Suggest editsRaise issue
Export items to CSVPreviousGet a documentNext