Tasks API Documentation

The Tasks API provides comprehensive task management capabilities for tracking customer interactions, follow-ups, support requests, and team workflows.

Base URL

https://api.talkingshops.com/v1

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

x-tenant-api-key: your_api_key_here

API keys are tenant-specific and automatically provide access to the correct data for your business account.

Rate Limiting

The API implements rate limiting to prevent abuse. Each tenant is limited to requests per minute based on their subscription tier.

Endpoints Overview

Method	Endpoint	Description
`POST`	`/tasks`	Create a new task
`GET`	`/tasks`	List tasks with filtering and pagination
`GET`	`/tasks/:taskId`	Get task by ID
`PUT`	`/tasks/:taskId`	Update a task
`PATCH`	`/tasks/:taskId`	Partial update a task
`POST`	`/tasks/:taskId/complete`	Mark task as completed
`POST`	`/tasks/:taskId/reassign`	Reassign task to another owner
`POST`	`/tasks/:taskId/snooze`	Snooze a task
`DELETE`	`/tasks/:taskId`	Delete a task
`GET`	`/tasks/stats`	Get task statistics
`GET`	`/tasks/analytics`	Get task analytics
`GET`	`/tasks/customer/:customerId`	Get tasks for a specific customer

Task Types

Task Status

Status	Description
`not_started`	Task has not been started
`in_progress`	Task is currently being worked on
`pending`	Task is waiting on external action
`completed`	Task has been completed
`deferred`	Task has been deferred

Task Priority

Priority	Description
`low`	Low priority task
`normal`	Normal priority task
`high`	High priority task
`urgent`	Urgent task requiring immediate attention

Task Title Types

Type	Description
`followup`	Follow-up with customer
`callback`	Return call to customer
`meeting`	Schedule or conduct meeting
`support`	Support request
`other`	Other task type

Task Outcomes

Outcome	Description
`resolved`	Task was successfully resolved
`no_answer`	Could not reach customer
`callback_scheduled`	Callback was scheduled
`escalated`	Task was escalated
`auto_completed`	Task was auto-completed
`other`	Other outcome

Create Task

Create a new task.

Request

http

POST /v1/tasks
Content-Type: application/json
x-tenant-api-key: your_api_key_here

{
  "title": "Follow up with customer",
  "titleType": "followup",
  "description": "Customer inquired about order #12345",
  "priority": "high",
  "dueDate": "2026-04-15T10:00:00Z",
  "ownerId": "agent_001",
  "ownerName": "John Doe",
  "relatedCustomerId": "cust_123",
  "relatedCustomerName": "Jane Smith",
  "tags": ["followup", "urgent"],
  "metadata": {
    "orderId": "ord_12345"
  }
}

Request Body

Field	Type	Required	Description
`title`	string	Yes	Task title (max 500 characters)
`titleType`	string	No	Type of task (followup, callback, meeting, support, other)
`description`	string	No	Task description (max 5000 characters)
`priority`	string	No	Priority level (low, normal, high, urgent)
`dueDate`	string	No	ISO 8601 date string for task due date
`ownerId`	string	No	ID of the agent assigned to the task
`ownerName`	string	No	Name of the agent assigned
`queueId`	string	No	Queue ID if task should be queued
`relatedCustomerId`	string	No	Linked customer ID
`relatedCustomerName`	string	No	Linked customer name
`relatedConversationId`	string	No	Linked conversation ID
`tags`	array	No	Task tags (max 20 tags, each max 50 chars)
`metadata`	object	No	Additional metadata (max 50 keys)

Response

json

{
  "success": true,
  "message": "Task created successfully",
  "task": {
    "_id": "507f1f77bcf86cd799439011",
    "title": "Follow up with customer",
    "titleType": "followup",
    "description": "Customer inquired about order #12345",
    "status": "not_started",
    "priority": "high",
    "outcome": null,
    "dueDate": "2026-04-15T10:00:00Z",
    "completedAt": null,
    "ownerId": "agent_001",
    "ownerName": "John Doe",
    "queueId": null,
    "claimStatus": "claimed",
    "claimedAt": "2026-04-10T12:00:00Z",
    "claimedBy": "agent_001",
    "relatedCustomerId": "cust_123",
    "relatedCustomerName": "Jane Smith",
    "relatedConversationId": null,
    "collaboratorIds": [],
    "completionNotes": null,
    "tags": ["followup", "urgent"],
    "metadata": { "orderId": "ord_12345" },
    "linkedEntity": null,
    "autoComplete": null,
    "agentReminders": null,
    "snoozedUntil": null,
    "snoozeCount": 0,
    "created_at": "2026-04-10T12:00:00Z",
    "updated_at": "2026-04-10T12:00:00Z"
  }
}

Task Object Fields

Field	Type	Description
`_id`	string	Unique task identifier
`title`	string	Task title
`titleType`	string	Type of task (followup, callback, meeting, support, other)
`description`	string	Task description
`status`	string	Task status
`priority`	string	Priority level (low, normal, high, urgent)
`outcome`	string \| null	Outcome if completed
`dueDate`	string \| null	Due date (ISO 8601)
`completedAt`	string \| null	Completion timestamp
`ownerId`	string	Assigned agent ID
`ownerName`	string	Assigned agent name
`queueId`	string \| null	Queue ID if task is queued
`claimStatus`	string	Claim status (unassigned, queued, claimed)
`claimedAt`	string \| null	When task was claimed
`claimedBy`	string \| null	Who claimed the task
`relatedCustomerId`	string \| null	Linked customer ID
`relatedCustomerName`	string	Linked customer name
`relatedConversationId`	string \| null	Linked conversation ID
`collaboratorIds`	array	IDs of collaborators
`completionNotes`	string \| null	Notes from completion
`tags`	array	Task tags
`metadata`	object	Custom metadata
`linkedEntity`	object \| null	Linked pipeline entity
`autoComplete`	object \| null	Auto-complete configuration
`agentReminders`	object \| null	Agent reminder settings
`snoozedUntil`	string \| null	Snooze deadline
`snoozeCount`	number	Number of times snoozed
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)

Error Response

json

{
  "error": {
    "code": "ValidationError",
    "message": "Validation failed",
    "details": ["title must be at least 1 characters"]
  }
}

List Tasks

Retrieve a paginated list of tasks with filtering.

Request

http

GET /v1/tasks?status=in_progress&priority=high&limit=20&page=1
x-tenant-api-key: your_api_key_here

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Items per page (max 100)
`sort`	string	dueDate	Sort field
`sortDirection`	string	asc	Sort direction (asc, desc)
`ownerId`	string	-	Filter by owner
`queueId`	string	-	Filter by queue
`status`	string	-	Filter by status
`priority`	string	-	Filter by priority
`relatedCustomerId`	string	-	Filter by customer
`linkedEntityType`	string	-	Filter by linked entity type
`linkedEntityId`	string	-	Filter by linked entity ID
`linkedPipelineId`	string	-	Filter by linked pipeline
`dueBefore`	string	-	Filter by due date before (ISO 8601)
`dueAfter`	string	-	Filter by due date after (ISO 8601)
`overdue`	boolean	-	Filter only overdue tasks
`search`	string	-	Search in title and description

Response

json

{
  "tasks": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "title": "Follow up with customer",
      "titleType": "followup",
      "status": "in_progress",
      "priority": "high",
      "dueDate": "2026-04-15T10:00:00Z",
      "ownerId": "agent_001",
      "ownerName": "John Doe",
      "claimStatus": "claimed",
      "created_at": "2026-04-10T12:00:00Z",
      "updated_at": "2026-04-10T12:00:00Z"
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 20,
  "totalPages": 8
}

Each task in the array contains the same fields as returned by the Create Task endpoint (see Task Object Fields above).

Get Task by ID

Retrieve a single task by its ID.

Request

http

GET /v1/tasks/:taskId
x-tenant-api-key: your_api_key_here

Response

json

{
  "_id": "507f1f77bcf86cd799439011",
  "title": "Follow up with customer",
  "status": "in_progress",
  "priority": "high",
  "ownerId": "agent_001",
  "ownerName": "John Doe",
  ...
}

Error Response

json

{
  "error": {
    "code": "NotFoundError",
    "message": "Task not found"
  }
}

Update Task

Update an existing task.

Request

http

PUT /v1/tasks/:taskId
Content-Type: application/json
x-tenant-api-key: your_api_key_here

{
  "title": "Updated title",
  "description": "Updated description",
  "priority": "urgent",
  "status": "in_progress"
}

Response

json

{
  "success": true,
  "message": "Task updated successfully"
}

Complete Task

Mark a task as completed.

Request

http

POST /v1/tasks/:taskId/complete
Content-Type: application/json
x-tenant-api-key: your_api_key_here

{
  "outcome": "resolved",
  "completionNotes": "Customer satisfied with resolution"
}

Request Body

Field	Type	Required	Description
`outcome`	string	No	Outcome of completion
`completionNotes`	string	No	Notes about completion (max 2000 chars)

Response

json

{
  "success": true,
  "message": "Task completed successfully"
}

Error Responses

404 Not Found - Task does not exist
400 Bad Request - Task is already completed or deferred

Snooze Task

Postpone a task by updating its due date.

Request

http

POST /v1/tasks/:taskId/snooze
Content-Type: application/json
x-tenant-api-key: your_api_key_here

{
  "newDueDate": "2026-04-16T10:00:00Z",
  "adjustReminders": true
}

Request Body

Field	Type	Required	Description
`newDueDate`	string	Yes	New due date (ISO 8601)
`adjustReminders`	boolean	No	Reset reminder timings (default: true)

Response

json

{
  "success": true,
  "message": "Task snoozed successfully",
  "snoozeCount": 2
}

Reassign Task

Transfer task ownership to another agent.

Request

http

POST /v1/tasks/:taskId/reassign
Content-Type: application/json
x-tenant-api-key: your_api_key_here

{
  "newOwnerId": "agent_002",
  "newOwnerName": "Jane Smith"
}

Request Body

Field	Type	Required	Description
`newOwnerId`	string	Yes	ID of new owner
`newOwnerName`	string	No	Name of new owner

Delete Task

Delete a task permanently.

Request

http

DELETE /v1/tasks/:taskId
x-tenant-api-key: your_api_key_here

Response

json

{
  "success": true,
  "message": "Task deleted successfully"
}

Get Task Statistics

Get aggregated task statistics.

Request

http

GET /v1/tasks/stats?ownerId=agent_001
x-tenant-api-key: your_api_key_here

Query Parameters

Parameter	Type	Description
`ownerId`	string	Filter stats by owner

Response

json

{
  "total": 45,
  "overdue": 5,
  "dueToday": 8,
  "completedThisWeek": 12,
  "inProgress": 20
}

Get Task Analytics

Get comprehensive task analytics with distributions and agent performance.

Request

http

GET /v1/tasks/analytics?startDate=2026-04-01&endDate=2026-04-30
x-tenant-api-key: your_api_key_here

Query Parameters

Parameter	Type	Description
`startDate`	string	Start date filter (ISO 8601)
`endDate`	string	End date filter (ISO 8601)
`ownerId`	string	Filter by owner

Response

json

{
  "totalTasks": 150,
  "completedTasks": 120,
  "overdueTasks": 5,
  "avgCompletionTime": 4.5,
  "statusDistribution": {
    "not_started": 10,
    "in_progress": 15,
    "completed": 120,
    "deferred": 5
  },
  "priorityDistribution": {
    "low": 30,
    "normal": 80,
    "high": 30,
    "urgent": 10
  },
  "agentPerformance": [
    {
      "agentId": "agent_001",
      "agentName": "John Doe",
      "total": 50,
      "completed": 45
    }
  ]
}

Get Customer Tasks

Retrieve all tasks related to a specific customer.

Request

http

GET /v1/tasks/customer/cust_123?page=1&limit=20
x-tenant-api-key: your_api_key_here

Response

json

{
  "tasks": [...],
  "total": 5,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}

Error Codes

Code	HTTP Status	Description
`AuthenticationError`	401	Invalid or missing API key
`ValidationError`	400	Request validation failed
`NotFoundError`	404	Resource not found
`InternalServerError`	500	Internal server error

Input Constraints

Field	Max Length
`title`	500 characters
`description`	5000 characters
`ownerName`	200 characters
`completionNotes`	2000 characters
`tags`	20 tags per task
`tag length`	50 characters per tag
`metadata keys`	50 keys
`metadata value`	1000 characters

Pagination Limits

Endpoint	Max Limit
List Tasks	100
Task Analytics	5000

Audit Events

All operations are logged with structured audit events:

Event	Description
`TASK_CREATED`	Task created
`TASK_UPDATED`	Task updated
`TASK_COMPLETED`	Task completed
`TASK_DELETED`	Task deleted
`TASK_REASSIGNED`	Task reassigned to new owner
`TASK_SNOOZED`	Task snoozed

Tasks API Documentation ​

Base URL ​

Authentication ​

Rate Limiting ​

Endpoints Overview ​

Task Types ​

Task Status ​

Task Priority ​

Task Title Types ​

Task Outcomes ​

Create Task ​

Request ​

Request Body ​

Response ​

Task Object Fields ​

Error Response ​

List Tasks ​

Request ​

Query Parameters ​

Response ​

Get Task by ID ​

Request ​

Response ​

Error Response ​

Update Task ​

Request ​

Response ​

Complete Task ​

Request ​

Request Body ​

Response ​

Error Responses ​

Snooze Task ​

Request ​

Request Body ​

Response ​

Reassign Task ​

Request ​

Request Body ​

Delete Task ​

Request ​

Response ​

Get Task Statistics ​

Request ​

Query Parameters ​

Response ​

Get Task Analytics ​

Request ​

Query Parameters ​

Response ​

Get Customer Tasks ​

Request ​

Response ​

Error Codes ​

Input Constraints ​

Pagination Limits ​

Audit Events ​

Tasks API Documentation

Base URL

Authentication

Rate Limiting

Endpoints Overview

Task Types

Task Status

Task Priority

Task Title Types

Task Outcomes

Create Task

Request

Request Body

Response

Task Object Fields

Error Response

List Tasks

Request

Query Parameters

Response

Get Task by ID

Request

Response

Error Response

Update Task

Request

Response

Complete Task

Request

Request Body

Response

Error Responses

Snooze Task

Request

Request Body

Response

Reassign Task

Request

Request Body

Delete Task

Request

Response

Get Task Statistics

Request

Query Parameters

Response

Get Task Analytics

Request

Query Parameters

Response

Get Customer Tasks

Request

Response

Error Codes

Input Constraints

Pagination Limits

Audit Events