> ## Documentation Index > Fetch the complete documentation index at: https://docs.zivio.com/llms.txt > Use this file to discover all available pages before exploring further. # List Tasks > The acting user's work queue: the outstanding tasks (to-do items, things that need their attention) the system has assigned to them — project approvals, questions to answer, invoices, milestones and variation orders to review, documents to check. By default returns only active tasks (pending and not dismissed by the user), ordered by due date; use filter[state]=all|completed|dismissed to widen it and filter[overdue]=true to triage. Each task carries `subject` (the record and project it is about) and `api_actions` (the V4 operations that action it); actioning the underlying record completes the task automatically a few seconds later, so a just-actioned task may briefly still read pending. Start with GET /tasks/summary for counts. ## Filtering Use the `filter[]` parameter to filter results. Multiple filters are combined with AND logic. ### Basic Examples ``` # Equality (implicit) GET /api/v4/tasks?filter[status]=pending # Multiple values (implicit IN) GET /api/v4/tasks?filter[status]=pending,cancelled # With explicit operator GET /api/v4/tasks?filter[created_at][gte]=2024-01-01 # Range query GET /api/v4/tasks?filter[completed_by_id][between]=10,100 # Multiple filters (AND) GET /api/v4/tasks?filter[status]=pending&filter[completed_by_id][gte]=10 ``` ### Available Attributes | Attribute | Type | Operators | Permitted Values | |-----------|------|-----------|------------------| | completed_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | completed_by_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | created_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | description | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | dismissed | boolean | `eq` | `true`, `false` | | due_on | date | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | name | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | overdue | boolean | `eq` | `true`, `false` | | state | string | `eq` | `active`, `all`, `completed`, `dismissed` | | status | string | `eq`, `not_eq`, `in`, `not_in` | `pending`, `completed`, `cancelled` | | taskable_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | taskable_scope | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | taskable_type | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | updated_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | ### OR Conditions Use `or[group]` to combine filter groups with OR logic. Filters within a group are ANDed: ``` # Simple OR GET /api/v4/tasks?or[1][status]=completed&or[2][status]=pending # Complex OR (status=completed AND completed_by_id>=10) OR (status=pending) GET /api/v4/tasks?or[1][status]=completed&or[1][completed_by_id][gte]=10&or[2][status]=pending ``` ## Sorting Use `sort[]` to order results. Default direction is ascending. ``` # Ascending (implicit) GET /api/v4/tasks?sort[created_at]= # Descending GET /api/v4/tasks?sort[created_at]=desc # Combined with filters GET /api/v4/tasks?filter[status]=pending&sort[created_at]=desc ``` ## OpenAPI ````yaml /api-reference/v4/openapi.json get /tasks openapi: 3.1.0 info: title: API V4 version: '4' description: >- OAuth 2.0 secured API. Obtain an access token using client credentials to access protected endpoints. The regional endpoints listed below serve every Zivio organisation, so each request — including the token request — must carry a `zivio-tenant-id` header identifying yours. Requests without it are rejected with a 404 before any token is checked. contact: name: API Support email: support@zivio.com servers: - url: https://api.zivio.net/api/v4 description: Global API Router - url: https://api.eu.zivio.net/api/v4 description: EU Data Region - url: https://api.uk.zivio.net/api/v4 description: UK Data Region - url: https://api.us.zivio.net/api/v4 description: US Data Region security: - oauth2: [] tenantId: [] paths: /tasks: get: tags: - Tasks summary: List Tasks description: >- The acting user's work queue: the outstanding tasks (to-do items, things that need their attention) the system has assigned to them — project approvals, questions to answer, invoices, milestones and variation orders to review, documents to check. By default returns only active tasks (pending and not dismissed by the user), ordered by due date; use filter[state]=all|completed|dismissed to widen it and filter[overdue]=true to triage. Each task carries `subject` (the record and project it is about) and `api_actions` (the V4 operations that action it); actioning the underlying record completes the task automatically a few seconds later, so a just-actioned task may briefly still read pending. Start with GET /tasks/summary for counts. ## Filtering Use the `filter[]` parameter to filter results. Multiple filters are combined with AND logic. ### Basic Examples ``` # Equality (implicit) GET /api/v4/tasks?filter[status]=pending # Multiple values (implicit IN) GET /api/v4/tasks?filter[status]=pending,cancelled # With explicit operator GET /api/v4/tasks?filter[created_at][gte]=2024-01-01 # Range query GET /api/v4/tasks?filter[completed_by_id][between]=10,100 # Multiple filters (AND) GET /api/v4/tasks?filter[status]=pending&filter[completed_by_id][gte]=10 ``` ### Available Attributes | Attribute | Type | Operators | Permitted Values | |-----------|------|-----------|------------------| | completed_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | completed_by_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | created_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | description | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | dismissed | boolean | `eq` | `true`, `false` | | due_on | date | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | | id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | name | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | overdue | boolean | `eq` | `true`, `false` | | state | string | `eq` | `active`, `all`, `completed`, `dismissed` | | status | string | `eq`, `not_eq`, `in`, `not_in` | `pending`, `completed`, `cancelled` | | taskable_id | integer | `eq`, `not_eq`, `in`, `not_in`, `gt`, `gte`, `lt`, `lte`, `between` | - | | taskable_scope | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | taskable_type | string | `eq`, `not_eq`, `in`, `not_in`, `like`, `not_like` | - | | updated_at | datetime | `eq`, `not_eq`, `gt`, `gte`, `lt`, `lte`, `between` | - | ### OR Conditions Use `or[group]` to combine filter groups with OR logic. Filters within a group are ANDed: ``` # Simple OR GET /api/v4/tasks?or[1][status]=completed&or[2][status]=pending # Complex OR (status=completed AND completed_by_id>=10) OR (status=pending) GET /api/v4/tasks?or[1][status]=completed&or[1][completed_by_id][gte]=10&or[2][status]=pending ``` ## Sorting Use `sort[]` to order results. Default direction is ascending. ``` # Ascending (implicit) GET /api/v4/tasks?sort[created_at]= # Descending GET /api/v4/tasks?sort[created_at]=desc # Combined with filters GET /api/v4/tasks?filter[status]=pending&sort[created_at]=desc ``` operationId: getTasks parameters: - name: page in: query schema: type: integer default: 1 description: Page number for pagination - name: limit in: query schema: type: integer default: 20 maximum: 100 description: Number of results per page (max 100) - name: filter[] in: query style: deepObject explode: true schema: type: object description: >- Filterable attributes: **integer** (operators: eq, not_eq, in, not_in, gt, gte, lt, lte, between): completed_by_id, id, taskable_id **datetime** (operators: eq, not_eq, gt, gte, lt, lte, between): completed_at, created_at, updated_at **string** (operators: eq, not_eq, in, not_in, like, not_like): description, name, state (one of: active = pending and not dismissed by you (the default, and the UI's task list); all = every task ever assigned to you, whatever its status; completed = completed tasks; dismissed = tasks you have dismissed from your list), status (one of: pending = still to be actioned; completed = actioned, by any assignee or automatically when the underlying work was done; cancelled = no longer relevant (the underlying record moved on)), taskable_scope, taskable_type **date** (operators: eq, not_eq, gt, gte, lt, lte, between): due_on **boolean** (operators: eq): dismissed (one of: true = dismissed from your list (other assignees still see it); false = still on your list), overdue (one of: true = pending and past its due date; false = not overdue (due today or later, no due date, or no longer pending)) Note: `like` is a case-insensitive substring match — pass the bare term (filter[title][like]=redesign). Do not add % wildcards; they are not needed. examples: equality: summary: Simple equality value: status: pending multiple_values: summary: Multiple values (implicit IN) value: status: pending,cancelled with_operator: summary: With explicit operator value: created_at: gte: '2024-01-01' range: summary: Range query value: completed_by_id: between: 10,100 - name: or[group] in: query style: deepObject explode: true schema: type: object description: >- OR condition groups. Filters within a group are ANDed; groups are ORed. **Syntax**: `or[group_key][]=value` or `or[group_key][][operator]=value` **Examples**: - Simple OR: `or[1][state]=draft&or[2][state]=pending` - Complex: `or[1][state]=draft&or[1][budget][gte]=50000&or[2][state]=closed` - With custom fields: `or[1][cf][priority]=high&or[2][state]=pending` Group keys can be any string (1, 2, a, b, etc.) - they just need to be unique. examples: simple_or: summary: Simple OR value: '1': status: completed '2': status: pending complex_or: summary: Complex OR with AND within groups value: '1': status: completed completed_by_id: gte: '10' '2': status: pending - name: sort[] in: query style: deepObject explode: true schema: type: object description: >- Sort results by attribute. Direction defaults to ascending. **Syntax**: `sort[]=` (ascending) or `sort[]=desc` (descending) **Sortable attributes**: completed_at, completed_by_id, created_at, description, dismissed, due_on, id, name, overdue, state, status, taskable_id, taskable_scope, taskable_type, updated_at **Examples**: - Ascending: `sort[created_at]=` or `sort[created_at]=asc` - Descending: `sort[created_at]=desc` examples: ascending: summary: Ascending (implicit) value: created_at: '' descending: summary: Descending value: created_at: desc responses: '200': description: List of tasks content: application/json: schema: type: object properties: tasks: type: array items: $ref: '#/components/schemas/Task' examples: success: summary: Successful response with tasks value: tasks: - id: 101 name: Acme Corporation description: Complete redesign of corporate website with modern UX status: completed due_on: '2024-01-16' overdue: false taskable_type: Example taskable_type taskable_id: 501 taskable_scope: Example taskable_scope subject: type: JobTriggeredApprovalStep id: 55 resource: type: Project id: 123 project_id: 123 project_title: Website Redesign supplier_name: Acme Consulting api_actions: - method: POST path: /api/v4/projects/123/approve completed_at: '2024-01-16T10:30:00+00:00' completed_by: id: 7 name: Jane Doe assignees: - id: 7 name: Jane Doe dismissed: false dismissed: false ui_path: /hiring/projects/123 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' - id: 102 name: Global Services Ltd description: Native iOS and Android application status: cancelled due_on: '2024-01-17' overdue: false taskable_type: Example taskable_type taskable_id: 502 taskable_scope: Example taskable_scope subject: type: JobTriggeredApprovalStep id: 55 resource: type: Project id: 123 project_id: 123 project_title: Website Redesign supplier_name: Acme Consulting api_actions: - method: POST path: /api/v4/projects/123/approve completed_at: '2024-01-17T10:30:00+00:00' completed_by: id: 7 name: Jane Doe assignees: - id: 7 name: Jane Doe dismissed: false dismissed: false ui_path: /hiring/projects/123 created_at: '2024-01-17T10:30:00+00:00' updated_at: '2024-01-17T10:30:00+00:00' empty: summary: Empty result set value: tasks: [] filtered: summary: Filtered results description: Results after applying filters value: tasks: - id: 101 name: Acme Corporation description: Complete redesign of corporate website with modern UX status: completed due_on: '2024-01-16' overdue: false taskable_type: Example taskable_type taskable_id: 501 taskable_scope: Example taskable_scope subject: type: JobTriggeredApprovalStep id: 55 resource: type: Project id: 123 project_id: 123 project_title: Website Redesign supplier_name: Acme Consulting api_actions: - method: POST path: /api/v4/projects/123/approve completed_at: '2024-01-16T10:30:00+00:00' completed_by: id: 7 name: Jane Doe assignees: - id: 7 name: Jane Doe dismissed: false dismissed: false ui_path: /hiring/projects/123 created_at: '2024-01-16T10:30:00+00:00' updated_at: '2024-01-16T10:30:00+00:00' '401': description: >- Unauthorized - the access token is missing, expired, revoked or malformed content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_token error_description: >- The access token provided is expired, revoked, malformed, or invalid for other reasons '403': description: Forbidden - insufficient scope content: application/json: schema: $ref: '#/components/schemas/Error' example: error: insufficient_scope error_description: >- The request requires higher privileges than provided by the access token required_scope: tasks:read provided_scopes: - welcome:read '422': description: Invalid filter or sort parameters content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_attribute: summary: Unknown filter attribute value: error: 'Invalid filter attribute: unknown_field' invalid_operator: summary: Invalid operator for type value: error: Operator 'like' is not valid for integer type invalid_value: summary: Invalid value format value: error: 'Invalid date format for created_at: not-a-date' invalid_sort_attribute: summary: Unknown sort attribute value: error: 'Invalid sort attribute: unknown_field' invalid_sort_direction: summary: Invalid sort direction value: error: Invalid sort direction 'random'. Must be 'asc' or 'desc' security: - oauth2: - tasks:read tenantId: [] components: schemas: Task: type: object properties: id: type: integer name: type: string description: type: string status: type: string enum: - pending - completed - cancelled example: pending due_on: type: string overdue: type: boolean example: true taskable_type: type: string taskable_id: type: integer taskable_scope: type: string subject: type: object description: >- What the task is about: the internal taskable, the record the api_actions act on, and the project it belongs to when there is one properties: type: type: string example: JobTriggeredApprovalStep id: type: integer example: 55 resource: oneOf: - type: object properties: type: type: string example: Project id: type: integer example: 123 - type: 'null' project_id: oneOf: - type: integer example: 123 - type: 'null' project_title: oneOf: - type: string example: Website Redesign - type: 'null' supplier_name: oneOf: - type: string example: Acme Consulting - type: 'null' api_actions: type: array description: >- V4 operations that action this kind of task, with ids filled in where known. Empty means the task can only be actioned in the web UI (use ui_path). Actioning the underlying record completes the task automatically, so prefer these over POST /tasks/{id}/complete. items: type: object properties: method: type: string example: POST path: type: string example: /api/v4/projects/123/approve completed_at: type: string completed_by: oneOf: - type: object properties: id: type: integer example: 7 name: type: string example: Jane Doe - type: 'null' assignees: type: array description: >- Every user the task was assigned to, with whether each has dismissed it items: type: object properties: id: type: integer example: 7 name: type: string example: Jane Doe dismissed: type: boolean example: false dismissed: type: boolean example: true ui_path: type: string example: /hiring/projects/123 description: Relative web UI path for a human to action the task created_at: type: string updated_at: type: string Error: type: object description: Error envelope returned by every non-2xx V4 response properties: error: type: string example: insufficient_scope error_description: type: string message: type: string details: type: object additionalProperties: true required_scope: type: string example: projects:read provided_scopes: type: array items: type: string securitySchemes: oauth2: type: oauth2 description: >- OAuth 2.0 client credentials. The access token from POST /oauth/token is sent as a bearer token. Request only the scopes you need. flows: clientCredentials: tokenUrl: https://api.zivio.net/api/v4/oauth/token scopes: bank_accounts:read: Read bank account details on suppliers and the org. catalogs:read: Read catalog items. cost_centers:read: Read cost center records. eoi_responses:read: Read responses to expressions of interest. eois:read: Read expressions of interest. offers:read: Read offers for projects. org_units:read: Read your organization unit hierarchy. org_users:read: Read members of your organization. resources:read: Read resource (worker) records. sales_invoices:read: Read invoices issued to clients. sales_milestones:read: Read milestones on sales engagements. skill_categories:read: Read the skill category taxonomy. skill_taxonomies:read: Read skill taxonomy structure. skills:read: Read individual skills. supplier_documents:read: Read documents uploaded by suppliers. supplier_lists:read: Read curated lists of suppliers. supplier_users:read: Read users belonging to supplier organizations. tax_types:read: Read configured tax types. users:read: Read user profiles. variation_orders:read: Read variation orders on projects. welcome:read: 'Required: confirms your identity to the application.' bid_evaluations:read: >- Read evaluation scorecards for bids, including criterion scores and quality, cost and total scores. bid_evaluations:write: >- Score bids against a project's quality criteria and override calculated cost scores. bids:read: Read bids submitted on projects. bids:write: >- Shortlist, select, eliminate and reinstate bids submitted on projects. invoices:read: Read invoices on projects. invoices:write: Create and update invoices. notes:read: Read notes on projects and EOIs. notes:write: Create and update notes on projects and EOIs. project_approvals:read: Read project approval workflows. project_approvals:write: Create and update project approval workflows. project_conversations:read: Read messages exchanged with suppliers on a project. project_conversations:write: Send messages to suppliers on a project. project_invitations:read: Read supplier invitations on projects. project_invitations:write: Invite suppliers to bid on projects. project_questions:read: Read supplier clarification questions on projects. project_questions:write: Answer and approve supplier clarification questions. projects:read: Read projects. projects:write: Create and update projects. milestones:read: Read milestones on projects. milestones:write: Create and update milestones. orgs:read: Read organization records. orgs:write: Create and update organization records. purchase_orders:read: Read purchase orders. purchase_orders:write: Create and update purchase orders. reviews:read: Read reviews left on suppliers. reviews:write: Create and update reviews. suppliers:read: Read supplier profiles. suppliers:write: Create and update supplier profiles. raw_scorecard_entries:write: Create and update raw scorecard entries. raw_scorecard_entries:read: Read raw scorecard entries. tasks:read: >- Read the acting user's task queue, including outstanding approvals and items to review. tasks:write: Complete and dismiss tasks in the acting user's task queue. act_as_user: >- Make requests as another user within the token holder's delegation boundary. tenantId: type: apiKey name: zivio-tenant-id in: header description: >- Your Zivio organisation identifier. The regional API endpoints serve every Zivio organisation, so each request must identify yours. ````