> ## 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 Companies > Retrieve a paginated list of companies. By default, only basic company data is returned with relationship IDs. Use the 'include' parameter to get detailed relationship data. ## Complex Usage Example ### Advanced Company Filtering with Full Context This example demonstrates advanced filtering with multiple parameters, relationship inclusion, business entity filtering, sorting, and pagination for retrieving companies: ```bash theme={null} curl -X GET "https://api.well.com/v1/companies?include=peoples,workspaces,emails,phones,web_links,locations,documents,media,categories,parents,subsidiaries&filter[workspace_id]=550e8400-e29b-41d4-a716-446655440000&filter[name]=TechCorp&filter[business_entity]=GmbH&filter[registration_tax_id]=12345678901&filter[registration_registered_value]=123456789&filter[country]=DE&filter[people_id]=550e8400-e29b-41d4-a716-446655440001&filter[email]=contact@techcorp.com&filter[phone_number]=+491234567890&filter[has_logo]=true&filter[created_at_from]=2024-01-01T00:00:00Z&filter[created_at_to]=2024-12-31T23:59:59Z&filter[updated_at_from]=2024-06-01T00:00:00Z&sort=-created_at&page[limit]=25&page[cursor]=eyJjcmVhdGVkX2F0IjoiMjAyNS0xMS0wMlQxMDozMDowMFoiLCJpZCI6ImNvbXBhbnk5LXV1aWQifQ==" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" ``` This comprehensive query will: * **Include relationships**: Retrieve complete data for people, workspaces, contact information, and documents * **Filter by workspace**: Limit to companies in a specific workspace * **Search by name**: Find companies with "TechCorp" in their name * **Filter by business entity**: Only show German GmbH companies * **Registration filtering**: Filter by tax ID and registration numbers * **Geographic filtering**: Limit to companies in Germany * **Contact filtering**: Find companies with specific email or phone * **Media filtering**: Only show companies with logos * **Date range filtering**: Limit to companies created/updated in specific periods * **Sorting**: Order by creation date (newest first) * **Pagination**: Get 25 results per page with cursor-based pagination ## 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"` ✅ | | `source_workspace_connector` | to-one (workspace\_connector) | `{ "source_workspace_connector": { "name": { "_eq": … } } }` | `"field": "source_workspace_connector.name"` ✅ | | `relations` | to-many (company\_relation) | `{ "relations": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `people` | to-many (company\_person) | `{ "people": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `social_links` | to-many (company\_web\_link) | `{ "social_links": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `locations` | to-many (company\_location) | `{ "locations": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `emails` | to-many (company\_email) | `{ "emails": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `phones` | to-many (company\_phone) | `{ "phones": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `categories` | to-many (company\_category) | `{ "categories": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `media` | to-many (company\_media) | `{ "media": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `company_financial` | to-one (company\_financial) | `{ "company_financial": { "field_name": { "_eq": … } } }` | `"field": "company_financial.field_name"` ✅ | | `company_workspace_connectors` | to-many (company\_workspace\_connector) | `{ "company_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": "companies", "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": "companies", "whereClause": { "relations": { "_some": { "field_name": { "_gt": 0 } } } } } ``` ## OpenAPI ````yaml GET /v1/companies 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/companies: get: summary: Get all companies description: >- Retrieve a paginated list of companies. By default, only basic company data is returned with relationship IDs. Use the 'include' parameter to get detailed relationship data. operationId: listCompanies parameters: - $ref: '#/components/parameters/AuthorizationHeader' - name: include in: query required: false schema: type: string enum: - workspace - company - people - documents - created_by - medias - web_links - emails - phones - categories - locations - people - parents - subsidiaries description: >- Include detailed relationship data in the response. Comma-separated values supported. example: workspace,people,emails - name: filter[created_at_from] in: query required: false schema: type: string format: date-time description: Filter companies created on or after this date example: '2025-01-01T00:00:00Z' - name: filter[created_at_to] in: query required: false schema: type: string format: date-time description: Filter companies created on or before this date example: '2025-12-31T23:59:59Z' - name: filter[updated_at_from] in: query required: false schema: type: string format: date-time description: Filter companies updated on or after this date example: '2025-01-01T00:00:00Z' - name: filter[updated_at_to] in: query required: false schema: type: string format: date-time description: Filter companies updated on or before this date example: '2025-12-31T23:59:59Z' - name: filter[created_by] in: query required: false schema: type: array items: type: string format: uuid description: Filter companies by creator ID(s) example: - 550e8400-e29b-41d4-a716-446655440000 - name: filter[workspace_id] in: query required: false schema: type: array items: type: string format: uuid description: Filter companies by workspace ID(s) example: - 550e8400-e29b-41d4-a716-446655440001 - name: filter[external_workspace_id] in: query required: false schema: type: array items: type: string description: Filter companies by external workspace ID(s) example: - ext-workspace-123 - name: filter[emails] in: query required: false schema: type: array items: type: string format: email description: Filter companies by email address(es) example: - contact@company.com - name: filter[phone] in: query required: false schema: type: array items: type: string description: Filter companies by phone number(s) example: - '+1234567890' - name: filter[parent_registration] in: query required: false schema: type: array items: type: string description: Filter companies by parent registration number(s) example: - HRB123456 - name: filter[documents_id] in: query required: false schema: type: array items: type: string format: uuid description: Filter companies by associated document ID(s) example: - 550e8400-e29b-41d4-a716-446655440002 - name: filter[parents_company_id] in: query required: false schema: type: array items: type: string format: uuid description: Filter companies by parent company ID(s) example: - 550e8400-e29b-41d4-a716-446655440003 - name: filter[parents_company_tax_id_value] in: query required: false schema: type: array items: type: string description: Filter companies by parent company tax ID value(s) example: - DE123456789 - name: filter[parents_company_registration_registered_value] in: query required: false schema: type: array items: type: string description: Filter companies by parent company registration value(s) example: - '123456789' - name: filter[domain_name_primary_link_url] in: query required: false schema: type: array items: type: string format: uri description: Filter companies by primary domain URL(s) example: - acme.com - name: sort in: query required: false schema: type: string enum: - created_at - '-created_at' - updated_at - '-updated_at' - issue_date - '-issue_date' - due_date - '-due_date' description: Sort companies by field. Use - prefix for descending order. example: '-created_at' responses: '200': description: Companies retrieved successfully content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/CompanyPostResponse' meta: type: object properties: pagination: type: object properties: page: type: integer limit: type: integer total: type: integer total_pages: type: integer example: data: - type: company id: 550e8400-e29b-41d4-a716-446655440000 attributes: name: TechCorp Solutions GmbH description: >- Leading technology company specializing in AI solutions and business automation business_entity: GmbH registration: tax_id: '12345678901' registered_value: '123456789' country: DE registration_number: value: HRB 123456 authority: Amtsgericht München has_logo: true workspace_id: - 550e8400-e29b-41d4-a716-446655440004 created_at: '2024-08-15T10:30:00Z' updated_at: '2024-12-01T14:22:00Z' relationships: created_by: data: type: user id: 550e8400-e29b-41d4-a716-446655440020 people: data: - type: people id: 550e8400-e29b-41d4-a716-446655440001 emails: data: - type: email id: 550e8400-e29b-41d4-a716-446655440010 phones: data: - type: phone id: 550e8400-e29b-41d4-a716-446655440011 web_links: data: - type: web_link id: 550e8400-e29b-41d4-a716-446655440012 media: data: - type: media id: 550e8400-e29b-41d4-a716-446655440014 documents: data: - type: document id: 550e8400-e29b-41d4-a716-446655440016 locations: data: - type: location id: 550e8400-e29b-41d4-a716-446655440013 workspaces: data: - type: workspace id: 550e8400-e29b-41d4-a716-446655440004 parents: data: - type: company id: 550e8400-e29b-41d4-a716-446655440017 subsidiaries: data: - type: company id: 550e8400-e29b-41d4-a716-446655440018 included: - type: people id: 550e8400-e29b-41d4-a716-446655440001 attributes: first_name: Klaus last_name: Weber full_name: Klaus Weber relationship_type: owner job_title: Founder & CEO - type: workspace id: 550e8400-e29b-41d4-a716-446655440004 attributes: name: European Operations description: Main workspace for European business operations created_at: '2024-01-10T08:15:00Z' - type: email id: 550e8400-e29b-41d4-a716-446655440010 attributes: value: contact@techcorp.com label: work is_verified: true is_primary: true - type: phone id: 550e8400-e29b-41d4-a716-446655440011 attributes: value: '+491234567890' label: work is_verified: true is_primary: true - type: web_link id: 550e8400-e29b-41d4-a716-446655440012 attributes: url: https://www.linkedin.com/company/techcorp-solutions platform: linkedin is_primary: true - type: location id: 550e8400-e29b-41d4-a716-446655440013 attributes: street: Maximilianstrasse 123 city: München postal_code: '80539' country: DE is_primary: true is_registered: true - type: media id: 550e8400-e29b-41d4-a716-446655440014 attributes: url: https://cdn.techcorp.com/logo.png media_type: logo is_primary: true - type: user id: 550e8400-e29b-41d4-a716-446655440020 attributes: first_name: John last_name: Doe email: john.doe@techcorp.com created_at: '2024-01-05T09:00:00Z' - type: document id: 550e8400-e29b-41d4-a716-446655440016 attributes: name: Company Registration Certificate file_name: registration_certificate.pdf mime_type: application/pdf size: 245760 is_public: false created_at: '2024-08-15T10:30:00Z' - type: company id: 550e8400-e29b-41d4-a716-446655440017 attributes: name: Global Tech Holdings description: Parent company of TechCorp Solutions business_entity: AG relationship_type: parent - type: company id: 550e8400-e29b-41d4-a716-446655440018 attributes: name: TechCorp Software Labs description: R&D subsidiary specializing in software development business_entity: GmbH relationship_type: subsidiary meta: pagination: total: 2 count: 2 per_page: 25 current_page: 1 total_pages: 1 '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: CompanyPostResponse: type: object properties: type: type: string const: company id: type: string format: uuid description: UUID of the created company example: 550e8400-e29b-41d4-a716-446655440000 attributes: $ref: '#/components/schemas/CompanyAttributes' relationships: $ref: '#/components/schemas/CompanyRelationshipsPostResponse' included: $ref: '#/components/schemas/CompanyIncludedResponse' 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 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 CompanyRelationshipsPostResponse: type: object properties: created_by: type: object properties: data: type: object properties: type: type: string const: people id: type: string format: uuid description: UUID of the person who created this company example: 550e8400-e29b-41d4-a716-446655440001 medias: type: object properties: data: type: array items: type: object properties: type: type: string const: media id: type: string format: uuid description: UUID of the media file example: 550e8400-e29b-41d4-a716-446655440002 web_links: type: object properties: data: type: array items: type: object properties: type: type: string const: web_link id: type: string format: uuid description: UUID of the web link example: 550e8400-e29b-41d4-a716-446655440003 emails: type: object properties: data: type: array items: type: object properties: type: type: string const: email id: type: string format: uuid description: UUID of the email example: 550e8400-e29b-41d4-a716-446655440004 phones: type: object properties: data: type: array items: type: object properties: type: type: string const: phone id: type: string format: uuid description: UUID of the phone example: 550e8400-e29b-41d4-a716-446655440005 locations: type: object properties: data: type: array items: type: object properties: type: type: string const: location id: type: string format: uuid description: UUID of the location example: 550e8400-e29b-41d4-a716-446655440007 people: type: object properties: data: type: array items: type: object properties: type: type: string const: people id: type: string format: uuid description: UUID of the person example: 550e8400-e29b-41d4-a716-446655440008 meta: type: object properties: relationship_type: type: string enum: - contact - employee - owner - other description: Relationship type of the person in the company example: employee documents: type: object properties: data: type: array items: type: object properties: type: type: string const: document id: type: string format: uuid description: UUID of the document example: 550e8400-e29b-41d4-a716-446655440009 parents: type: object properties: data: type: array items: type: object properties: type: type: string const: company id: type: string format: uuid description: UUID of the parent company example: 550e8400-e29b-41d4-a716-446655440012 subsidiaries: type: object properties: data: type: array items: type: object properties: type: type: string const: company id: type: string format: uuid description: UUID of the subsidiary company example: 550e8400-e29b-41d4-a716-446655440013 workspaces: type: object properties: data: type: array items: type: object properties: type: type: string const: workspace id: type: string format: uuid description: UUID of the workspace example: 632860b5-48b7-49eb-9dd1-8bddc634f387 CompanyIncludedResponse: type: object description: >- Object containing included resources referenced in relationships, organized by resource type. These are the actual created/linked resources with real UUIDs. properties: created_by: type: object description: Person who created this company properties: data: type: object properties: type: type: string const: people id: type: string format: uuid description: UUID of the person attributes: $ref: '#/components/schemas/PeopleAttributes' people: type: object description: Person associated with the company properties: data: type: object properties: type: type: string const: people id: type: string format: uuid description: UUID of the person attributes: $ref: '#/components/schemas/PeopleAttributes' parents: type: object description: Parent company of this company 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' subsidiaries: type: object description: Subsidiary companies of this company properties: data: type: array items: type: object properties: type: type: string const: company id: type: string format: uuid description: UUID of the subsidiary company attributes: $ref: '#/components/schemas/CompanyAttributes' workspaces: type: object description: Workspaces associated with this company properties: data: type: array items: type: object properties: type: type: string const: workspace id: type: string format: uuid description: UUID of the workspace attributes: $ref: '#/components/schemas/WorkspaceAttributes' emails: type: object description: Email addresses associated with this company properties: data: type: array items: type: object properties: type: type: string const: email id: type: string format: uuid description: UUID of the email attributes: $ref: '#/components/schemas/EmailAttributes' required: - type - id - attributes phones: type: object description: Phone numbers associated with this company properties: data: type: array items: type: object properties: type: type: string const: phone id: type: string format: uuid description: UUID of the phone attributes: $ref: '#/components/schemas/PhoneAttributes' locations: type: object description: Locations/addresses associated with this company properties: data: type: array items: type: object properties: type: type: string const: location id: type: string format: uuid description: UUID of the location attributes: $ref: '#/components/schemas/LocationAttributes' media: type: object description: Media files associated with this company properties: data: type: array items: type: object properties: type: type: string const: media id: type: string format: uuid description: UUID of the media attributes: $ref: '#/components/schemas/MediaAttributes' web_links: type: object description: Web links associated with this company properties: data: type: array items: type: object properties: type: type: string const: web_link id: type: string format: uuid description: UUID of the web link attributes: $ref: '#/components/schemas/WebLinkAttributes' documents: type: object description: Documents associated with this company properties: data: type: array items: type: object properties: type: type: string const: document id: type: string format: uuid description: UUID of the document attributes: $ref: '#/components/schemas/DocumentAttributes' PeopleAttributes: type: object properties: first_name: type: string description: The person's first name last_name: type: string description: The person's last name full_name: type: string description: The person's full name (typically first_name + last_name) created_at: type: string format: date-time description: Timestamp when the person was created updated_at: type: string format: date-time description: Timestamp when the person was last updated additionalProperties: false WorkspaceAttributes: type: object properties: name: type: string description: Workspace name desription: type: string description: Workspace description external_workspace_id: type: string format: uuid description: external workspace id avatar_color: type: string format: colors description: Color of the avatar created_at: type: string format: date-time description: Timestamp when the workspace was created updated_at: type: string format: date-time description: Timestamp when the workspace was last updated EmailAttributes: type: object properties: value: type: string format: email description: Email address value example: sarah.wilson@techcorp.com is_primary: type: boolean default: true description: >- Whether this is the primary email address. Defaults to 'false', unless no other email is marked as primary (in which case it becomes 'true'). Only one email can be marked as primary per person/company. example: true label: type: string enum: - work - personal - other - ... description: >- Email label type. See [all available labels](/enums/label) for complete list. default: work example: work created_at: type: string format: date-time description: Timestamp when the email was created example: '2023-06-15T10:30:00Z' updated_at: type: string format: date-time description: Timestamp when the email was last updated example: '2023-06-15T10:30:00Z' PhoneAttributes: type: object properties: number: type: string pattern: ^\+[1-9]\d{1,14}$ description: Full international phone number in E164 format example: '+14155552671' label: type: string enum: - work - personal - other - ... description: >- Phone label type. See [all available labels](/enums/label) for complete list. is_primary: type: boolean description: Whether this is the primary phone number created_at: type: string format: date-time description: Timestamp when the phone was created LocationAttributes: type: object properties: full_address: type: string description: Complete formatted address address_line1: type: string description: Primary address line address_line2: type: string description: Secondary address line city: type: string description: City name region: type: string description: State, province, or region postal_code: type: string description: Postal or ZIP code country: type: string description: Two-letter ISO country code latitude: type: number format: float description: Geographic latitude coordinate longitude: type: number format: float description: Geographic longitude coordinate is_primary: type: boolean description: Whether this is the primary location is_registered: type: boolean description: Whether this is a registered business address label: type: string description: Custom label for the location created_at: type: string format: date-time description: Date and time when the location was created updated_at: type: string format: date-time description: Date and time when the location was last updated MediaAttributes: type: object properties: media_type: type: string enum: - avatar - logo - banner url: type: string format: uri description: URL to the media file is_primary: type: boolean description: Whether this is the primary media processed_at: type: - string format: date-time description: Timestamp when media processing completed uploaded_at: type: string format: date-time WebLinkAttributes: type: object properties: platform: type: string enum: - website - linkedin - x - github description: Web platform type url: type: string description: Full profile URL created_at: type: string format: date-time description: Date and time when the web link was created updated_at: type: string format: date-time description: Date and time when the web link was updated 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 ````