> ## Documentation Index > Fetch the complete documentation index at: https://docs.dolfinai.co/llms.txt > Use this file to discover all available pages before exploring further. # List bills > List bills for the organisation with optional state, supplier, invoice number, tag, and date filtering. ## OpenAPI ````yaml /api-reference/openapi.json get /bills openapi: 3.1.1 info: title: Dolfin API description: >- Dolfin API for AR & AP. Authenticate using the `x-dolfin-api-key` header with the API key distributed to your organisation. version: v1 servers: - url: https://api.dolfinai.co description: Production security: - {} tags: - name: Webhooks - name: Users - name: TaxRates - name: Suppliers - name: Supplier Credit Notes - name: Bills - name: SpendCategories - name: Payables - name: RecurringInvoices - name: Receivables - name: Purchase Orders - name: Products - name: Payments - name: Invoices - name: Organisations - name: Members - name: MCP - name: Matching - name: Invoice Reminders - name: Industries - name: Gmail - name: Delivery Notes - name: Customers - name: Currencies - name: Credit Notes - name: Clients - name: ClientInvites - name: BankPayments - name: Bank details - name: Auth - name: ApprovalPolicies - name: ApiKeys - name: Agent paths: /bills: get: tags: - Bills summary: List bills description: >- List bills for the organisation with optional state, supplier, invoice number, tag, and date filtering. parameters: - name: Cursor in: query schema: type: string - name: Limit in: query schema: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string format: int32 default: 20 - name: States in: query schema: type: array items: $ref: '#/components/schemas/BillState' - name: SupplierId in: query schema: type: string format: uuid - name: InvoiceNumber in: query schema: type: string - name: Tag in: query schema: type: string - name: DueDateFrom in: query schema: type: string format: date-time - name: DueDateTo in: query schema: type: string format: date-time responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/PagedResponseOfBillResponse' '400': description: Pagination.InvalidCursor — the cursor value is invalid content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' components: schemas: BillState: enum: - Created - OcrProcessing - PendingReview - NeedsApproval - Approved - Rejected - Scheduled - Paid - OcrFailed - PaymentInProgress - PaymentFailed - Voided PagedResponseOfBillResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/BillResponse' meta: $ref: '#/components/schemas/PagedResponseMeta' ProblemDetails: type: object properties: type: type: - 'null' - string title: type: - 'null' - string status: pattern: ^-?(?:0|[1-9]\d*)$ type: - 'null' - integer - string format: int32 detail: type: - 'null' - string instance: type: - 'null' - string BillResponse: type: object properties: id: type: string format: uuid organisationId: type: string format: uuid state: $ref: '#/components/schemas/BillState' source: $ref: '#/components/schemas/BillSource' fileName: type: - 'null' - string rawFileType: type: - 'null' - string supplierId: type: - 'null' - string format: uuid suggestedMatchedSupplierId: type: - 'null' - string description: Will be used as the Supplier if the Supplier is not set format: uuid supplierName: type: - 'null' - string supplierEmail: type: - 'null' - string supplierPhone: type: - 'null' - string supplierAddress: type: - 'null' - string supplierTaxId: type: - 'null' - string supplierWebsite: type: - 'null' - string supplierRegistrationNumber: type: - 'null' - string invoiceNumber: type: - 'null' - string invoiceDate: type: - 'null' - string format: date-time dueDate: type: - 'null' - string format: date-time currency: type: string description: ISO 4217 currency code (e.g. GBP, USD, EUR) subTotal: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string format: double taxAmount: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string format: double totalAmount: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string format: double amountCredited: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string description: Supplier credit netted against this bill. format: double outstanding: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string description: >- What's left to pay after supplier credit (TotalAmount − AmountCredited). This is what the payment flow charges. format: double paymentTerms: type: - 'null' - string paymentRef: type: - 'null' - string bankDetails: $ref: '#/components/schemas/BankDetails' ocrConfidence: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$ type: - 'null' - number - string format: float approvedBy: type: - 'null' - string format: uuid approvedAt: type: - 'null' - string format: date-time rejectedBy: type: - 'null' - string format: uuid rejectedAt: type: - 'null' - string format: date-time rejectionReason: type: - 'null' - string voidedBy: type: - 'null' - string description: >- Set when Voided. A null VoidedBy with a non-null VoidedAt ⇒ policy auto-void. format: uuid voidedAt: type: - 'null' - string format: date-time voidReason: type: - 'null' - string appliedApprovalPolicyId: type: - 'null' - string description: The approval policy applied at submit-review, if any (UI badge). format: uuid appliedApprovalPolicyName: type: - 'null' - string approvalReasoning: type: - 'null' - string description: Deterministic explanation of the approval decision. resolvedApproverUserIds: type: array items: type: string format: uuid description: >- Users this bill was routed to for approval — the pending reviewers while in NeedsApproval. paymentDate: type: - 'null' - string format: date-time paymentMethod: type: - 'null' - string paidAt: type: - 'null' - string format: date-time createdAt: type: string format: date-time createdBy: type: - 'null' - string format: uuid updatedAt: type: string format: date-time updatedBy: type: - 'null' - string format: uuid supplier: oneOf: - type: 'null' - $ref: '#/components/schemas/SupplierResponse' lineItems: type: array items: $ref: '#/components/schemas/BillLineItemResponse' tags: type: array items: type: string description: >- Distinct union of the line items' tags, baked at submit-review — for bill-level filtering. PagedResponseMeta: type: object properties: cursors: $ref: '#/components/schemas/PagedResponseCursors' BillSource: enum: - Upload - Email - Webhook BankDetails: type: object properties: accountHolderName: type: - 'null' - string accountNumber: type: - 'null' - string sortCode: type: - 'null' - string routingNumber: type: - 'null' - string iban: type: - 'null' - string bicSwift: type: - 'null' - string country: type: - 'null' - string description: ISO 3166-1 alpha-2 country code (e.g. GB, US, DE) currency: type: - 'null' - string description: ISO 4217 currency code (e.g. GBP, USD, EUR) SupplierResponse: required: - name type: object properties: id: type: string format: uuid organisationId: type: string format: uuid name: type: string email: type: - 'null' - string phone: type: - 'null' - string website: type: - 'null' - string taxNumber: type: - 'null' - string registrationNumber: type: - 'null' - string address: oneOf: - type: 'null' - $ref: '#/components/schemas/Address' bankDetails: $ref: '#/components/schemas/BankDetails' bankDetailsVerified: type: boolean bankDetailsVerifiedAt: type: - 'null' - string format: date-time paymentTermsDefault: type: - 'null' - string createdAt: type: string format: date-time createdBy: type: - 'null' - string format: uuid updatedAt: type: string format: date-time updatedBy: type: - 'null' - string format: uuid BillLineItemResponse: required: - description type: object properties: id: type: string format: uuid description: type: string quantity: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string format: double unit: type: - 'null' - string description: >- Optional unit of measure as it appears on the document (e.g. kg, box, hrs). unitPrice: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string format: double taxRate: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string description: >- Tax rate as a percentage (e.g. 20 for 20%). Descriptive metadata only — TaxAmount is the authoritative figure and is not derived from this rate. format: double taxAmount: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string format: double subTotal: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ type: - number - string format: double sortOrder: pattern: ^-?(?:0|[1-9]\d*)$ type: - integer - string format: int32 category: type: - 'null' - string spendClass: oneOf: - type: 'null' - $ref: '#/components/schemas/SpendClass' tags: type: array items: type: string categoryConfirmed: type: boolean spendClassConfirmed: type: boolean suggestedCategory: type: - 'null' - string categoryConfidence: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$ type: - 'null' - number - string format: double suggestedSpendClass: oneOf: - type: 'null' - $ref: '#/components/schemas/SpendClass' spendClassConfidence: pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$ type: - 'null' - number - string format: double PagedResponseCursors: type: object properties: current: type: - 'null' - string next: type: - 'null' - string previous: type: - 'null' - string Address: type: object properties: line1: type: - 'null' - string line2: type: - 'null' - string city: type: - 'null' - string postalCode: type: - 'null' - string country: type: - 'null' - string description: ISO 3166-1 alpha-2 country code (e.g. GB, US, DE) SpendClass: enum: - Fixed - Variable - null ````