> ## 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 Document > Retrieve a list of documents with optional filtering, sorting, and relationship inclusion. By default, only document IDs are returned for relationships. ## Complex Usage Example ### Advanced Document Filtering with Full Context This example demonstrates advanced filtering with multiple parameters, relationship inclusion, file type filtering, and sorting for retrieving documents: ```bash theme={null} curl -X GET "https://api.well.com/v1/documents?include=media,invoice&filter[workspace_id]=550e8400-e29b-41d4-a716-446655440000&filter[status]=completed&filter[file_type]=pdf&filter[uploaded_at][from]=2024-01-01T00:00:00Z&filter[uploaded_at][to]=2024-12-31T23:59:59Z&filter[processed_at][from]=2024-06-01T00:00:00Z&sort=-uploaded_at&limit=25" \ -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 | | ---------------------------- | ------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------- | | `workspace` | to-one (workspace) | `{ "workspace": { "name": { "_eq": … } } }` | `"field": "workspace.name"` ✅ | | `collect` | to-one (collect) | `{ "collect": { "field_name": { "_eq": … } } }` | `"field": "collect.field_name"` ✅ | | `source_workspace_connector` | to-one (workspace\_connector) | `{ "source_workspace_connector": { "name": { "_eq": … } } }` | `"field": "source_workspace_connector.name"` ✅ | | `invoices` | to-many (invoice) | `{ "invoices": { "_some": { "grand_total": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `transaction_documents` | to-many (transaction\_document) | `{ "transaction_documents": { "_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": "documents", "whereClause": { "workspace": { "name": { "_ilike": "%acme%" } } }, "orderBy": { "field": "workspace.name", "direction": "asc" } } ``` **Filter by a to-many relation** (quantified — bare nesting is invalid): ```json theme={null} { "root": "documents", "whereClause": { "invoices": { "_some": { "grand_total": { "_gt": 0 } } } } } ``` ## OpenAPI ````yaml GET /v1/documents 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/documents: get: summary: List documents description: >- Retrieve a list of documents with optional filtering, sorting, and relationship inclusion. By default, only document IDs are returned for relationships. parameters: - $ref: '#/components/parameters/AuthorizationHeader' - name: include in: query required: false schema: type: string enum: - media - invoice description: >- Include detailed relationship data in the response. Comma-separated values supported. example: media,invoice - name: filter[uploaded_at][from] in: query required: false schema: type: string format: date-time description: Filter documents uploaded from this date/time example: '2024-01-01T00:00:00Z' - name: filter[uploaded_at][to] in: query required: false schema: type: string format: date-time description: Filter documents uploaded up to this date/time example: '2024-12-31T23:59:59Z' - name: filter[processed_at][from] in: query required: false schema: type: string format: date-time description: Filter documents processed from this date/time example: '2024-01-01T00:00:00Z' - name: filter[processed_at][to] in: query required: false schema: type: string format: date-time description: Filter documents processed up to this date/time example: '2024-12-31T23:59:59Z' - name: filter[workspace_id] in: query required: false schema: type: string format: uuid description: Filter documents by workspace ID example: 550e8400-e29b-41d4-a716-446655440000 - name: filter[external_workspace_id] in: query required: false schema: type: string description: Filter documents by external workspace ID example: ext-workspace-123 - name: filter[status] in: query required: false schema: type: string enum: - pending - processing - completed - failed - deleted description: Filter documents by processing status example: completed - name: filter[file_type] in: query required: false schema: type: string enum: - pdf - image - word - excel - text description: Filter documents by file type example: pdf - name: sort in: query required: false schema: type: string enum: - uploaded_at - '-uploaded_at' - processed_at - '-processed_at' description: Sort documents by field. Use - prefix for descending order. example: '-uploaded_at' - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 description: Number of documents per page example: 20 responses: '200': description: Documents retrieved successfully content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Document' example: data: - type: document id: 550e8400-e29b-41d4-a716-446655440010 attributes: file_name: invoice_2024.pdf workspace_id: 550e8400-e29b-41d4-a716-446655440001 collect_id: 550e8400-e29b-41d4-a716-446655440002 metadata: source_number: '+33123456789' target_number: '+33987654321' document_type: invoice created_at: '2024-01-20T10:30:00Z' updated_at: '2024-01-20T10:30:00Z' relationships: workspace: data: type: workspace id: 550e8400-e29b-41d4-a716-446655440001 company: data: type: company id: 550e8400-e29b-41d4-a716-446655440003 people: data: type: people id: 550e8400-e29b-41d4-a716-446655440004 meta: phone_number: '+33123456789' included: - type: workspace id: 550e8400-e29b-41d4-a716-446655440001 attributes: name: Sales Team Workspace description: Workspace for sales documents and invoices avatar_color: '#4A90E2' external_workspace_id: sales_ws_001 auto_extract_enabled: true created_at: '2024-01-15T09:00:00Z' updated_at: '2024-01-15T09:00:00Z' - type: company id: 550e8400-e29b-41d4-a716-446655440003 attributes: name: ACME Corporation description: Leading technology and consulting company locale: fr domain_name_primary_link_url: acme.com tax_id: value: FR12345678901 type: VAT registration: trade_name: ACME registered_name: ACME Corporation SAS registration_number: business_type: SAS value: RCS 123456789 registry_name: Registre du Commerce Paris registry_country: FR created_at: '2024-01-10T08:00:00Z' updated_at: '2024-01-10T08:00:00Z' - type: people id: 550e8400-e29b-41d4-a716-446655440004 attributes: first_name: Jean last_name: Dupont full_name: Jean Dupont created_at: '2024-01-12T10:00:00Z' updated_at: '2024-01-12T10:00:00Z' 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: Document: type: object properties: id: type: string type: type: string enum: - document attributes: $ref: '#/components/schemas/DocumentAttributes' relationships: type: object properties: company: type: object properties: data: type: object properties: type: type: string enum: - company id: type: string people: type: object properties: data: type: object properties: type: type: string enum: - people id: type: string meta: type: object properties: phone_number: type: string 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 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 ````