Skip to main content
GET
/
v1
/
documents
List documents
curl --request GET \
  --url https://api.wellapp.ai/v1/documents \
  --header 'Authorization: <authorization>'
{
  "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
  }
}

​
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: 
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"
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. This resource’s related objects (the ones you can include) and how to filter or sort on each:
RelationshipCardinalityFilter on a fieldSort by a field
workspaceto-one (workspace){ "workspace": { "name": { "_eq": … } } }"field": "workspace.name" ✅
collectto-one (collect){ "collect": { "field_name": { "_eq": … } } }"field": "collect.field_name" ✅
source_workspace_connectorto-one (workspace_connector){ "source_workspace_connector": { "name": { "_eq": … } } }"field": "source_workspace_connector.name" ✅
invoicesto-many (invoice){ "invoices": { "_some": { "grand_total": { "_eq": … } } } }aggregate proxy only ⚠️
transaction_documentsto-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): 
{
  "root": "documents",
  "whereClause": { "workspace": { "name": { "_ilike": "%acme%" } } },
  "orderBy": { "field": "workspace.name", "direction": "asc" }
}
Filter by a to-many relation (quantified — bare nesting is invalid): 
{
  "root": "documents",
  "whereClause": { "invoices": { "_some": { "grand_total": { "_gt": 0 } } } }
}

Headers

​
Authorization
string
required

Bearer token for authentication

Query Parameters

​
include
enum<string>

Include detailed relationship data in the response. Comma-separated values supported.

Available options:
media,
invoice
​
filter[uploaded_at][from]
string<date-time>

Filter documents uploaded from this date/time

​
filter[uploaded_at][to]
string<date-time>

Filter documents uploaded up to this date/time

​
filter[processed_at][from]
string<date-time>

Filter documents processed from this date/time

​
filter[processed_at][to]
string<date-time>

Filter documents processed up to this date/time

​
filter[workspace_id]
string<uuid>

Filter documents by workspace ID

​
filter[external_workspace_id]
string

Filter documents by external workspace ID

​
filter[status]
enum<string>

Filter documents by processing status

Available options:
pending,
processing,
completed,
failed,
deleted
​
filter[file_type]
enum<string>

Filter documents by file type

Available options:
pdf,
image,
word,
excel,
text
​
sort
enum<string>

Sort documents by field. Use - prefix for descending order.

Available options:
uploaded_at,
-uploaded_at,
processed_at,
-processed_at
​
limit
integer
default:20

Number of documents per page

Required range: 1 <= x <= 100

Response

Documents retrieved successfully

​
data
object[]