> ## Documentation Index > Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get Invoices > Retrieve a list of invoices filtered by issuer, receiver, status or date range. Supports pagination following JSON:API specification. ## Complex Usage Example ### Advanced Invoice Filtering with Full Context This example demonstrates advanced filtering with multiple parameters, status filtering, company relationships, and pagination for retrieving invoices: ```bash theme={null} curl -X GET "https://api.well.com/v1/invoices?issuer_id=550e8400-e29b-41d4-a716-446655440001&receiver_id=550e8400-e29b-41d4-a716-446655440002&status=sent&date_from=2025-01-01&date_to=2025-12-31&page[limit]=20&page[cursor]=eyJkYXRlIjoiMjAyNS0xMS0wMiIsImlkIjoiaW52b2ljZTktdXVpZCJ9" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" ``` ## Filtering & sorting on related objects Filter and sort on a **related (included) object** by nesting into the relationship — the same relationships you pass to `include`. * **To-one** relations nest directly: `{ "issuer": { "name": { "_eq": "Acme" } } }`, and sort by a dot-path: `"orderBy": { "field": "issuer.name", "direction": "asc" }`. * **To-many** relations must be quantified with `_some`, `_every`, or `_none`: `{ "items": { "_some": { "quantity": { "_gt": 1 } } } }`. They are **not** directly sortable (a to-many sort needs an aggregate proxy). * **Composite** `composite_*` columns are virtual — filter and sort on their underlying source fields, not on the composite. Workspace row-level security applies at every hop, so a related-object filter never widens your tenant scope. Full operator set, deep-nesting rules, and pagination notes: [Filtering & sorting](/api-reference/filtering-and-sorting). This resource's related objects (the ones you can `include`) and how to filter or sort on each: | Relationship | Cardinality | Filter on a field | Sort by a field | | ------------------------------ | --------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------- | | `issuer` | to-one (company) | `{ "issuer": { "name": { "_eq": … } } }` | `"field": "issuer.name"` ✅ | | `receiver` | to-one (company) | `{ "receiver": { "name": { "_eq": … } } }` | `"field": "receiver.name"` ✅ | | `document` | to-one (document) | `{ "document": { "file_name": { "_eq": … } } }` | `"field": "document.file_name"` ✅ | | `workspace` | to-one (workspace) | `{ "workspace": { "name": { "_eq": … } } }` | `"field": "workspace.name"` ✅ | | `source_workspace_connector` | to-one (workspace\_connector) | `{ "source_workspace_connector": { "name": { "_eq": … } } }` | `"field": "source_workspace_connector.name"` ✅ | | `exchange_rate` | to-one (exchange\_rate) | `{ "exchange_rate": { "rate_date": { "_eq": … } } }` | `"field": "exchange_rate.rate_date"` ✅ | | `subscription` | to-one (subscription) | `{ "subscription": { "status": { "_eq": … } } }` | `"field": "subscription.status"` ✅ | | `invoice_items` | to-many (invoice\_item) | `{ "invoice_items": { "_some": { "amount": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `invoice_transactions` | to-many (invoice\_transaction) | `{ "invoice_transactions": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `payment_means` | to-many (invoice\_payment\_means) | `{ "payment_means": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `invoice_workspace_connectors` | to-many (invoice\_workspace\_connector) | `{ "invoice_workspace_connectors": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️ | Replace `field_name` with any field of the related object. See its object-reference page for the full field list. **Filter by a to-one relation** (and sort by it): ```json theme={null} { "root": "invoices", "whereClause": { "issuer": { "name": { "_ilike": "%acme%" } } }, "orderBy": { "field": "issuer.name", "direction": "asc" } } ``` **Filter by a to-many relation** (quantified — bare nesting is invalid): ```json theme={null} { "root": "invoices", "whereClause": { "invoice_items": { "_some": { "amount": { "_gt": 0 } } } } } ``` ## OpenAPI ````yaml GET /v1/invoices openapi: 3.1.0 info: title: Well Document API version: 1.0.0 description: API for uploading and managing financial documents in the Well platform servers: - url: https://api.wellapp.ai security: [] paths: /v1/invoices: get: summary: List invoices description: >- Retrieve a list of invoices filtered by issuer, receiver, status or date range. Supports pagination following JSON:API specification. parameters: - $ref: '#/components/parameters/AuthorizationHeader' - name: issuer_id in: query schema: type: string description: Filter invoices where the specified company is the issuer. - name: receiver_id in: query schema: type: string description: Filter invoices where the specified company is the receiver. - name: status in: query schema: type: string enum: - draft - sent - paid - cancelled description: Filter invoices by status. - name: date_from in: query schema: type: string format: date description: Filter invoices issued on or after this date (YYYY-MM-DD). - name: date_to in: query schema: type: string format: date description: Filter invoices issued on or before this date (YYYY-MM-DD). - name: page[limit] in: query schema: type: integer minimum: 1 maximum: 100 default: 20 description: Number of invoices per page. - name: page[cursor] in: query schema: type: string description: Cursor for pagination. - name: include in: query schema: type: string enum: - company - payment_means - people - document description: >- Include related resources in the response. Multiple relationships can be included by separating them with commas. responses: '200': description: Invoices retrieved successfully content: application/vnd.api+json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/InvoiceResponse' meta: type: object properties: total: type: integer description: Total number of invoices page: type: integer description: Current page number limit: type: integer description: Number of invoices per page example: data: - type: invoice id: invoice_550e8400-e29b-41d4-a716-446655440000 attributes: reference_number: INV-2025-001 document_type: commercial_invoice document_type_code: '380' issue_date: '2025-01-15' due_date: '2025-02-15' local_currency: EUR local_totals: subtotal: '1000.00' tax_total: '200.00' total_amount: '1200.00' terms: Payment due within 30 days billing_context: subscription payment_status: paid: true amount_paid: 123 amount_remaining: 123 status: draft description: Professional services invoice for January 2025 created_at: '2025-01-15T10:30:00Z' updated_at: '2025-01-15T10:30:00Z' relationships: issuer: data: type: company id: company-issuer-uuid receiver: data: type: company id: company-receiver-uuid payment_means: data: - type: payment_means id: pm_1 invoice_items: data: - type: invoice_item id: item_1 document: data: type: document id: doc_original_invoice people: data: - type: people id: 3c90c3cc-0d44-4b50-8888-8dd25736052a included: - type: people id: 3c90c3cc-0d44-4b50-8888-8dd25736052a attributes: first_name: John last_name: Smith full_name: John Smith email: jsmith@example.com created_at: '2023-11-07T05:31:56Z' updated_at: '2023-11-07T05:31:56Z' - type: document id: doc_original_invoice attributes: file_name: invoice_2025_001.pdf status: processed uploaded_at: '2023-11-07T05:31:56Z' processed_at: '2023-11-07T05:31:56Z' file_type: application/pdf size_bytes: 245678 created_at: '2023-11-07T05:31:56Z' updated_at: '2023-11-07T05:31:56Z' - type: invoice_item id: item_1 attributes: line_id: '1' sku: WM-1001 name: Wireless Mouse description: Ergonomic wireless mouse with USB receiver unit_price: 25 currency: EUR unit: EA min_quantity: 1 max_quantity: 500 tax: rate: 20 category: standard scheme: VAT period: start: '2025-06-26' end: '2025-06-27' created_at: '2025-05-11T13:42:12Z' updated_at: '2025-05-11T13:45:20Z' - type: payment_means id: pm_1 attributes: type: card_details scheme: SEPA status: active account_details: iban: DE89370400440532013000 bic: COBADEFFXXX account_number: '532013000' routing_number: '37040044' currency: EUR bank_details: bank_name: Commerzbank AG bank_code: '37040044' branch_name: Main Branch branch_code: '440' card_details: masked_pan: '****1234' brand: visa card_type: credit expiry_month: 12 expiry_year: 2027 cardholder_name: John Smith digital_wallet: provider: paypal wallet_id: john.smith@example.com wallet_type: personal compliance: kyc_status: verified aml_status: cleared sanctions_check: passed last_compliance_check: '2023-11-07T05:31:56Z' metadata: source: api external_id: ext_pm_12345 nickname: Primary Payment Method description: Main company payment account tags: - primary - sepa created_at: '2023-11-07T05:31:56Z' updated_at: '2023-11-07T05:31:56Z' - type: company id: company-receiver-uuid attributes: name: ACME Corporation description: Technology solutions provider domain_name_primary_link_url: acme.com locale: en tax_id: value: DE123456789 type: VAT registration: trade_name: TechSol registered_name: ACME Corporation GmbH registration_number: business_type: GmbH value: HRB 123456 registry_name: Handelsregister Berlin registry_country: DE workspace_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a created_at: '2023-11-07T05:31:56Z' updated_at: '2023-11-07T05:31:56Z' - type: company id: company-issuer-uuid attributes: name: Service Provider Inc description: Professional services company domain_name_primary_link_url: serviceprovider.com locale: en tax_id: value: FR987654321 type: VAT registration: trade_name: Service Provider registered_name: Service Provider Inc. registration_number: business_type: Inc value: RCS 987654 registry_name: Paris Commercial Registry registry_country: FR workspace_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a created_at: '2023-11-07T05:31:56Z' updated_at: '2023-11-07T05:31:56Z' meta: total: 150 page: 1 limit: 20 '401': description: Unauthorized - invalid API key content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' components: parameters: AuthorizationHeader: name: Authorization in: header required: true schema: type: string description: Bearer token for authentication schemas: InvoiceResponse: type: object properties: data: type: object properties: type: type: string enum: - invoice description: Resource type identifier id: type: string format: uuid description: Unique identifier for the created invoice example: invoice_550e8400-e29b-41d4-a716-446655440000 attributes: type: object properties: reference_number: type: string description: Unique reference number for the invoice example: INV-2025-001 document_type: type: string description: Type of invoice document example: commercial_invoice document_type_code: type: string description: Standard document type code example: '380' issue_date: type: string format: date description: Date when the invoice was issued example: '2025-01-15' due_date: type: string format: date description: Payment due date example: '2025-02-15' local_currency: type: string description: Currency code for the invoice example: EUR local_totals: type: object properties: subtotal: type: string description: Subtotal before taxes and discounts example: '1000.00' tax_total: type: string description: Total tax amount example: '200.00' total_amount: type: string description: Final total amount example: '1200.00' terms: type: string description: Contractual payment terms billing_context: type: string description: Billing context identifier example: subscription payment_status: type: object properties: paid: type: boolean amount_paid: type: number amount_remaining: type: number status: type: string enum: - draft - sent - viewed - accepted - rejected - cancelled description: Invoice lifecycle status example: draft description: type: string description: Invoice description or notes example: Professional services invoice for January 2025 created_at: type: string format: date-time description: Timestamp when the invoice was created example: '2025-01-15T10:30:00Z' updated_at: type: string format: date-time description: Timestamp when the invoice was last updated example: '2025-01-15T10:30:00Z' relationships: type: object properties: issuer: type: object properties: data: type: object properties: type: type: string const: company id: type: string example: company-uuid description: uuid of company description: Company issuing the invoice receiver: type: object properties: data: type: object properties: type: type: string const: company id: type: string example: company-uuid description: uuid of company description: Company receiving the invoice payment_means: type: object properties: data: type: array items: type: object properties: type: type: string const: payment_means id: type: string example: pm_1 description: Associated payment methods invoice_items: type: object properties: data: type: array items: type: object properties: type: type: string const: payment_means id: type: string example: pm_1 description: Line items included in the invoice document: type: object properties: data: type: object properties: type: type: string const: document id: type: string example: document-uuid description: uuid of document description: Supporting document attached to the invoice people: $ref: '#/components/schemas/PersonsRelationshipData' description: Relationships with other resources included: type: object properties: documents: type: object description: Supporting document attached to the invoice properties: data: type: object properties: type: type: string const: company id: type: string format: uuid description: UUID of the parent company attributes: $ref: '#/components/schemas/DocumentAttributes' invoice_items: type: object description: Correspondent/intermediary banks for routing (optional) properties: data: type: object properties: type: type: string const: company id: type: string format: uuid description: UUID of the parent company attributes: $ref: '#/components/schemas/InvoiceItemsAttributes' payment_means: type: object description: Correspondent/intermediary banks for routing (optional) properties: data: type: object properties: type: type: string const: company id: type: string format: uuid description: UUID of the parent company attributes: $ref: '#/components/schemas/PaymentMeansAttributes' receiver: type: object description: Correspondent/intermediary banks for routing (optional) properties: data: type: object properties: type: type: string const: company id: type: string format: uuid description: UUID of the parent company attributes: $ref: '#/components/schemas/CompanyAttributes' issuer: type: object description: Correspondent/intermediary banks for routing (optional) properties: data: type: object properties: type: type: string const: company id: type: string format: uuid description: UUID of the parent company attributes: $ref: '#/components/schemas/CompanyAttributes' description: Response schema for successfully created invoice UnauthorizedError: type: object properties: code: type: string example: UNAUTHORIZED description: Error code identifier status: type: integer example: 401 description: HTTP status code title: type: string example: Unauthorized description: Error title message: type: string example: You are not authorized to access this resource description: Detailed error message meta: type: object properties: log_id: type: string format: uuid example: 65c669d4-679c-4a8b-b8c0-fbe37699bb5b description: Unique identifier for tracking this error in logs required: - log_id required: - code - status - title - message - meta PersonsRelationshipData: type: object properties: data: type: array items: $ref: '#/components/schemas/PersonReference' DocumentAttributes: type: object properties: file_name: type: string status: type: string uploaded_at: type: string format: date-time processed_at: type: string format: date-time file_type: type: string size_bytes: type: integer InvoiceItemsAttributes: type: object properties: line_id: type: string description: Line identifier within the invoice example: '1' sku: type: string description: Stock Keeping Unit identifier example: WM-1001 name: type: string description: Product or service name example: Wireless Mouse description: type: string description: Detailed description of the item example: Ergonomic wireless mouse with USB receiver unit_price: type: number format: decimal minimum: 0 description: Unit price in local currency example: 25 currency: type: string pattern: ^[A-Z]{3}$ description: ISO 4217 currency code example: EUR unit: type: string description: Unit of measurement example: EA min_quantity: type: integer minimum: 0 description: Minimum quantity allowed example: 1 max_quantity: type: integer minimum: 1 description: Maximum quantity allowed example: 500 tax: type: object properties: rate: type: number format: decimal minimum: 0 maximum: 100 description: Tax rate as percentage example: 20 category: type: string description: Tax category example: standard scheme: type: string description: Tax scheme identifier example: VAT period: type: object properties: start: type: string format: date description: Service period start date example: '2025-06-26' end: type: string format: date description: Service period end date example: '2025-06-27' created_at: type: string format: date-time description: Creation timestamp example: '2025-05-11T13:42:12Z' updated_at: type: string format: date-time description: Last update timestamp example: '2025-05-11T13:45:20Z' PaymentMeansAttributes: type: object properties: type: type: string enum: - card_details - account_details - wallet_details - cash_details - check_details - crypto_details - other description: >- Type of payment means. See [payment means types](/enums/payment-means) for details. scheme: type: string enum: - SEPA - SWIFT - ACH - FASTER_PAYMENTS - VISA - MASTERCARD - AMEX - PAYPAL - APPLEPAY - GOOGLEPAY - STRIPE - LOCAL - OTHER description: >- Payment scheme or network. See [scheme types](/enums/sheme-type) for details. status: type: string enum: - active - inactive - pending_verification - suspended - expired - blocked description: >- Current status of the payment means. See [payment means status](/enums/payment-means-status) for details. account_details: type: object description: Bank account details for account_details type properties: iban: type: string description: International Bank Account Number bic: type: string description: Bank Identifier Code (SWIFT) account_number: type: string description: Local account number (alternative to IBAN) routing_number: type: string description: Bank routing number (US ACH) currency: type: string description: Currency code (ISO 4217) bank_details: type: object description: Additional bank information properties: bank_name: type: string description: Name of the bank bank_code: type: string description: Bank code or identifier branch_name: type: string description: Bank branch name branch_code: type: string description: Bank branch code card_details: type: object description: Credit/debit card details for card_details type properties: masked_pan: type: string description: Masked Primary Account Number (PCI DSS compliant) brand: type: string enum: - visa - mastercard - amex - discover - diners - jcb - unionpay - other description: Card brand card_type: type: string enum: - credit - debit - prepaid - charge description: Type of card expiry_month: type: integer description: Card expiry month expiry_year: type: integer description: Card expiry year cardholder_name: type: string description: Name as printed on card digital_wallet: type: object description: Digital wallet details for wallet_details type properties: provider: type: string enum: - paypal - applepay - googlepay - stripe - square - venmo - cashapp - other description: Digital wallet provider wallet_id: type: string description: Wallet identifier (email, phone, etc.) wallet_type: type: string enum: - personal - business - merchant description: Type of wallet account compliance: type: object description: Compliance and verification status properties: kyc_status: type: string enum: - pending - in_progress - completed - failed - not_required description: Know Your Customer verification status aml_status: type: string enum: - pending - in_progress - cleared - flagged - not_required description: Anti-Money Laundering check status sanctions_check: type: string enum: - pending - passed - failed - not_required description: Sanctions screening status last_compliance_check: type: string format: date-time description: Last compliance check timestamp metadata: type: object description: System metadata properties: source: type: string enum: - api - dashboard - import - connector description: How the payment means was created external_id: type: string description: External system identifier nickname: type: string description: User-friendly name for the payment means description: type: string description: Additional description of the payment means tags: type: array items: type: string description: Tags for categorization created_at: type: string format: date-time description: Creation timestamp updated_at: type: string format: date-time description: Last update timestamp CompanyAttributes: type: object properties: description: type: string domain_name_primary_link_url: type: string format: url maxLength: 500 description: >- The domain url from the website or email address of the company. Used as unique identifier in some cases. examples: - acme.com tax_id: type: object properties: value: description: Tax ID issued by local or national tax authority. type: string examples: - DE123456789 type: description: >- Type of tax ID, useful for applying formatting and validation rules. type: string examples: - VAT registration: type: object properties: trade_name: description: Commercial or branding name (if different from registered name). type: string examples: - TechSol registered_name: description: Legal company name. type: string minLength: 1 maxLength: 100 examples: - Red Hat Inc. registration_number: type: object properties: business_type: description: Legal entity structure type. type: string examples: - GmbH value: description: Official company registration number. type: string examples: - HRB 123456 registry_name: description: Name of the official registration body. type: string examples: - Handelsregister Berlin registry_country: description: Country of the registry authority. (string (ISO 3166-1 alpha-2)) type: string examples: - DE workspace_id: type: string format: uuid description: UUID of the workspace associated with this company created_at: type: string format: date-time updated_at: type: string format: date-time PersonReference: type: object properties: type: type: string const: people id: type: string format: uuid description: UUID of the person attributes: type: object properties: first_name: type: string last_name: type: string full_name: type: string email: type: string format: email created_at: type: string format: date-time required: - type - id ````