Description

Overview

The Tasks API provides functionality for managing tasks and assignments:

Task creation and management
Task assignments and reassignments
Task status tracking
Task categories
Multi-assignee support
Task performance tracking
Task history and audit logs

Core Concepts

Task Statuses

pending: Task is awaiting action
in_progress: Task is being worked on
completed: Task has been completed
canceled: Task was canceled
declined: Task was declined

Task Categories

sign: Document signing tasks
approve: Approval tasks
update: Update tasks
delete: Deletion tasks

Task Actions

decline: Decline a task
cancel: Cancel a task
performed: Mark task as performed
reassign: Reassign task to different users

Endpoints

Task Management

Create Task

POST /v1/customers/{customer_id}/tasks

Create a new task.

Request Body:

{
  "title": "Review Document",
  "category": "approve",
  "description": "Please review and approve the document",
  "is_urgent": true,
  "objects": [
    {
      "type": "invoice",
      "content": "contract.pdf"
    }
  ],
  "assignees": ["uuid1", "uuid2"],
  "weight": 1.0,
  "metadata": {
    "department": "legal",
    "priority": "high"
  }
}

Response:

{
  "id": "uuid",
  "title": "Review Document",
  "category": "approve",
  "description": "Please review and approve the document",
  "is_urgent": true,
  "status": "pending",
  "weight": 1.0,
  "performed_weight": 0.0,
  "customer_id": "uuid",
  "assignees": [
    {
      "id": "uuid",
      "name": "John Doe",
      "task_id": "uuid",
      "user_id": "uuid1",
      "status": "pending",
      "weight": 0.5,
      "task_completed": false,
      "assigned_at": "2024-03-21T10:00:00Z"
    }
  ],
  "created_at": "2024-03-21T10:00:00Z",
  "created_by": "uuid",
  "metadata": {
    "department": "legal",
    "priority": "high",
    "logs": [],
    "actions": {}
  }
}

Get All Tasks

GET /v1/customers/{customer_id}/tasks

Retrieve all tasks with optional filtering.

Query Parameters:

status: Filter by status (comma-separated)
is_urgent: Filter urgent tasks
category: Filter by category
not_created_by: Exclude tasks created by user

Get Task

GET /v1/customers/{customer_id}/tasks/{id}

Get a specific task.

Get Task Categories

GET /v1/customers/tasks/categories

Get available task categories.

Response:

{
  "sign": {
    "title": "Sign Document",
    "icon": "signature"
  },
  "approve": {
    "title": "Approve Document",
    "icon": "check"
  }
}

Delete Task

DELETE /v1/customers/{customer_id}/tasks/{id}

Delete a task.

Task Actions

Perform Task

PATCH /v1/customers/{customer_id}/tasks/{id}/perform

Mark a task as performed.

Reassign Task

PATCH /v1/customers/{customer_id}/tasks/{id}/reassign

Reassign task to different users.

Request Body:

{
  "assignees": ["uuid1", "uuid2"],
  "metadata": {
    "reason": "Original assignee unavailable"
  }
}

Cancel Task

PATCH /v1/customers/{customer_id}/tasks/{id}/cancel

Cancel a task.

Decline Task

PATCH /v1/customers/{customer_id}/tasks/{id}/decline

Decline a task.

Task Assignees

Get Task Assignees

GET /v1/customers/{customer_id}/tasks/{id}/assignees

Get task assignees.

Error Handling

All errors follow a standard format:

{
  "code": "error_code",
  "message": "Error description"
}

Error Codes

Task Errors

Code	Description
tasks_m.task_not_found	Task not found
tasks_m.customer_not_found	Customer not found
tasks_m.assignees_not_found	Assignees not found
tasks_m.assignee_not_found	Specific assignee not found
tasks_m.persona_not_found	Persona not found
tasks_m.ineligible_to_perform_task	User ineligible to perform task
tasks_m.task_already_exists	Task already exists
tasks_m.invalid_task_data	Invalid task data provided
tasks_m.invalid_category	Invalid task category

Operation Errors

Code	Description
tasks_m.failed_to_create_task	Failed to create task
tasks_m.failed_to_update_task	Failed to update task
tasks_m.failed_to_delete_task	Failed to delete task
tasks_m.failed_to_cancel_task	Failed to cancel task
tasks_m.failed_to_list_tasks	Failed to list tasks
tasks_m.failed_to_perform_task	Failed to perform task
tasks_m.failed_to_reassign_task	Failed to reassign task
tasks_m.failed_to_decline_task	Failed to decline task
tasks_m.failed_to_retrieve_tasks	Failed to retrieve tasks

Task Workflow

Task Creation
- Task is created with assignees
- Initial status is "pending"
- Assignees are notified
Task Processing
- Assignees can perform, decline, or request reassignment
- Task weight is tracked per assignee
- Actions are logged in metadata
Task Completion
- Task is marked complete when all required weights are met
- Final status is updated
- Task history is preserved

On this page