> ## 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. # List People > Page through a workspace's people. Filtering and sorting (including across related objects) is done through the records query. `GET /v1/people` returns the workspace's people (contacts), **page-paginated** with `page` and `limit` (max 100). It does **not** accept inline filtering or sorting — those query params are ignored. To filter or sort people — including across related objects — use the records query: `POST /v1/records/query` with `root: "people"`. It exposes the full `filters` / raw `whereClause` and `orderBy` model. For the operator set and pagination notes see [Filtering & sorting](/api-reference/filtering-and-sorting). ## 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 (workspaceconnector) | `{ "source_workspace_connector": { "field_name": { "_eq": … } } }` | `"field": "source_workspace_connector.field_name"` ✅ | | `media` | to-one (media) | `{ "media": { "file_name": { "_eq": … } } }` | `"field": "media.file_name"` ✅ | | `emails` | to-many (personemail) | `{ "emails": { "_some": { "address": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `phones` | to-many (personphone) | `{ "phones": { "_some": { "number": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `locations` | to-many (personlocation) | `{ "locations": { "_some": { "city": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `web_links` | to-many (personweblink) | `{ "web_links": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `companies` | to-many (companyperson) | `{ "companies": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `memberships` | to-many (membership) | `{ "memberships": { "_some": { "role": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `collect` | to-many (collect) | `{ "collect": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `workspace_connectors` | to-many (workspaceconnector) | `{ "workspace_connectors": { "_some": { "field_name": { "_eq": … } } } }` | aggregate proxy only ⚠️ | | `people_workspace_connectors` | to-many (peopleworkspaceconnector) | `{ "people_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": "people", "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": "people", "whereClause": { "emails": { "_some": { "address": { "_ilike": "%@acme.com" } } } } } ``` ## OpenAPI ````yaml GET /v1/people 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/people: get: summary: List people description: >- Returns the workspace's people (contacts), page-paginated. This endpoint takes only `page` and `limit` — it does not accept inline filtering or sorting. For filtering and sorting (including across related objects), use `POST /v1/records/query` with `root: "people"`; see Filtering & sorting. parameters: - $ref: '#/components/parameters/AuthorizationHeader' - name: page in: query schema: type: integer default: 1 minimum: 1 description: 1-based page number. - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 20 description: People per page (max 100). responses: '200': description: A page of people. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Person' meta: type: object properties: pagination: type: object properties: page: type: integer example: 1 limit: type: integer example: 20 total: type: integer example: 137 total_pages: type: integer example: 7 required: - page - limit - total - total_pages required: - data '401': description: Authentication required or invalid API key. components: parameters: AuthorizationHeader: name: Authorization in: header required: true schema: type: string description: Bearer token for authentication schemas: Person: type: object description: >- Central entity representing individuals with comprehensive contact information properties: id: type: string format: uuid description: Unique person identifier (UUID v4) example: 550e8400-e29b-41d4-a716-446655440000 type: type: string const: people description: JSON:API resource type identifier attributes: $ref: '#/components/schemas/PersonAttributes' relationships: $ref: '#/components/schemas/PersonRelationships' included: $ref: '#/components/schemas/PeopleIncludedPost' required: - id - type - attributes PersonAttributes: type: object description: Person attribute data properties: first_name: type: string description: Person's first name example: Marie minLength: 1 maxLength: 100 last_name: type: string description: Person's last name example: Dubois minLength: 1 maxLength: 100 full_name: type: string description: Auto-computed full name (first + last) example: Marie Dubois readOnly: true created_at: type: string format: date-time description: Person creation timestamp (UTC) example: '2024-01-15T10:30:00Z' readOnly: true updated_at: type: - string - 'null' format: date-time description: Last modification timestamp (UTC) example: '2024-01-16T14:20:00Z' readOnly: true required: - first_name - last_name - created_at PersonRelationships: type: object description: Person relationship references properties: emails: type: object description: Email addresses associated with this person properties: data: type: array items: type: object properties: type: type: string const: email id: type: string description: >- UUID of an existing email or temp-id that references an email defined in the included array required: - type - id phones: type: object description: Phone numbers associated with this person properties: data: type: array items: type: object properties: type: type: string const: phone id: type: string description: >- UUID of an existing phone or temp-id that references a phone defined in the included array required: - type - id web_links: type: object description: Social media profiles associated with this person properties: data: type: array items: type: object properties: type: type: string const: social_link id: type: string description: >- UUID of an existing web link or temp-id that references a web link defined in the included array required: - type - id companies: type: object description: Companies associated with this person properties: data: type: array items: type: object properties: type: type: string const: company id: type: string description: >- UUID of an existing company or temp-id that references a company defined in the included array required: - type - id workspaces: type: object description: Workspaces this person belongs to properties: data: type: array items: type: object properties: type: type: string const: workspace id: type: string description: >- UUID of an existing workspace or temp-id that references a workspace defined in the included array required: - type - id documents: type: object description: Documents associated with this person properties: data: type: array items: type: object properties: type: type: string const: document id: type: string description: >- UUID of an existing document or temp-id that references a document defined in the included array required: - type - id memberships: type: object description: Workspace memberships with roles and permissions properties: data: type: array items: type: object properties: type: type: string const: membership id: type: string description: >- UUID of an existing membership or temp-id that references a membership defined in the included array required: - type - id medias: type: object description: medias of the person properties: data: type: array items: type: object properties: type: type: string const: media id: type: string description: >- UUID of an existing media or temp-id that references a media defined in the included array required: - type - id PeopleIncludedPost: type: object properties: emails: type: object properties: data: type: array items: type: object properties: type: type: string const: email id: type: string attributes: $ref: '#/components/schemas/EmailAttributes' required: - type - id - attributes phones: type: object properties: data: type: array items: type: object properties: type: type: string const: phone id: type: string description: >- temp-id that references a phones defined in the included array attributes: $ref: '#/components/schemas/PhoneCreateAttributes' required: - type - id - attributes 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 description: >- temp-id that references a web links defined in the included array attributes: $ref: '#/components/schemas/WebLinkCreateAttributes' required: - type - id - attributes companies: type: object properties: data: type: array items: type: object properties: type: type: string const: company id: type: string description: >- temp-id that references a companies defined in the included array attributes: $ref: '#/components/schemas/CompanyCreateAttributes' required: - type - id - attributes 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 description: >- temp-id that references a workspaces defined in the included array attributes: $ref: '#/components/schemas/WorkspaceCreateAttributes' required: - type - id - attributes 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 description: >- temp-id that references a documents defined in the included array attributes: $ref: '#/components/schemas/DocumentCreateAttributes' memberships: type: object description: membership associated with this person properties: data: type: array items: type: object properties: type: type: string const: membership id: type: string description: >- temp-id that references a memberships defined in the included array attributes: $ref: '#/components/schemas/MembershipCreateAttributes' medias: type: object description: Media associated with this person properties: data: type: array items: type: object properties: type: type: string const: membership id: type: string description: >- temp-id that references a medias defined in the included array attributes: $ref: '#/components/schemas/MediaCreateAttributes' 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' PhoneCreateAttributes: type: object properties: number: type: string pattern: ^\+[1-9]\d{1,14}$ description: Phone number in E164 format example: '+14155552671' is_primary: type: boolean description: Whether this is the primary phone number default: true label: type: string enum: - work - personal - other - ... description: >- Phone label type. See [all available labels](/enums/label) for complete list. default: work required: - number WebLinkCreateAttributes: type: object properties: platform: type: string enum: - website - linkedin - x - github description: Web platform type url: type: string minLength: 1 maxLength: 500 description: Full profile URL required: - url CompanyCreateAttributes: type: object properties: locale: type: string pattern: ^[a-z]{2}(-[A-Z]{2})?$ description: >- Language settings.That’s the locale for the business relationship. Emails or documents can be used to identify the locale. Default EN. example: en-US domain_name_primary_link_url: type: string format: uri description: >- The domain url from the website or email address of the company. Used as unique identifier in some cases. example: https://www.techcorp.com tax_id: type: object properties: value: type: string description: Tax ID issued by local or national tax authority. example: DE123456789 type: type: string description: >- Type of tax ID, useful for applying formatting and validation rules.[all tax id types](/enums/tax-id) See all available labels for complete list. example: - VAT - TVA - IVA - ... registration: oneOf: - type: object properties: trade_name: type: string description: >- Commercial or branding name (if different from registered name). example: TechSol registered_name: type: string description: Legal company name example: TechCorp AI Solutions LLC required: - registered_name - type: object properties: trade_name: type: string description: >- Commercial or branding name (if different from registered name). example: TechSol registered_name: type: string description: Legal company name example: TechCorp AI Solutions LLC required: - trade_name registration_number: type: object properties: business_type: type: string enum: - Inc - Corp - LLC - GmbH - Ltd - SA - SAS description: >- Legal entity structure type. See [all business entity types](/enums/business-entity-by-country) for complete list. example: GmbH value: type: string description: Official company registration number. example: HRB 123456 registry_name: type: string description: >- Name of the official registration body. See [all available registry name](/enums/registry-name) for complete list. example: Handelsregister Berlin registry_country: type: string pattern: ^[A-Z]{2}$ description: |- Country of the registry authority. Must be valid ISO country code example: DE, FR, US, etc. description: type: string minLength: 1 maxLength: 500 description: Company description explaining business purpose in max 2 sentences. example: An innovative technology company focused on AI solutions required: - registration WorkspaceCreateAttributes: type: object properties: name: type: string minLength: 1 maxLength: 255 description: Workspace name description: type: string maxLength: 1000 description: Workspace description avatar_color: type: string pattern: ^#[A-Fa-f0-9]{6}$ description: 'Avatar color in hexadecimal format (e.g., #FF5733)' external_workspace_id: type: string minLength: 1 maxLength: 255 description: External workspace identifier required: - name DocumentCreateAttributes: type: object properties: file_name: type: string status: type: string file_type: type: string size_bytes: type: integer MembershipCreateAttributes: type: object properties: firebase_id: type: string role: type: string enum: - admin - member - owner - ... description: >- User role in the workspace. See [all available roles](/enums/role) for complete list. required: - role MediaCreateAttributes: type: object properties: media_type: type: string enum: - avatar - logo - banner description: Type of media (avatar, logo, banner) is_primary: type: boolean default: true description: 'Marks preferred media. Default: true' ````