Skip to main content
TypeScript

Authorizations

Authorization
string
header
required

Your Periskope API token, sent as Authorization: Bearer <token>. Generate one from the Periskope dashboard under Settings → API & Webhooks. API access requires an active Pro or Enterprise plan.

Path Parameters

task_id
string
required

Unique id of the task (task-xxxxxxxxxxxxxxxx), returned when the task was created

Minimum string length: 1
Example:

"task-aaaaaaaaaaaa"

Response

The task

A task in the workspace. Tasks are either standalone to-dos (type: todo) or linked to a chat, message or ticket via association. Tasks belong to the workspace as a whole, not to a specific phone.

task_id
string

Unique id of the task (task-xxxxxxxxxxxxxxxx). Use this value as the task_id path parameter when fetching or updating the task.

Example:

"task-aaaaaaaaaaaa"

title
string

Title of the task, up to 500 characters

Example:

"Call back the customer about the renewal quote"

type
enum<string>

Kind of task: 'todo' for a standalone task, or 'chat', 'message' or 'ticket' for a task linked to that object. Immutable after creation.

Available options:
todo,
chat,
message,
ticket
Example:

"message"

status
enum<string>

Lifecycle status of the task: 'open', 'inprogress' or 'closed'

Available options:
open,
inprogress,
closed
Example:

"open"

priority
integer

Priority of the task: 1 (low), 2 (medium) or 3 (high)

Example:

2

assignee
string

Email of the workspace member the task is assigned to. null when the task is unassigned.

Example:

"user@example.com"

created_by
string

Who created the task: a member's email, or "api" when created via the API without a created_by

Example:

"api"

last_updated_by
string

Who last changed the task: a member's email, or "api" for API changes without a last_updated_by

Example:

"api"

created_at
string

When the task was created, as an ISO 8601 timestamp

Example:

"2026-01-15T09:30:00.000Z"

last_updated_at
string

When the task was last updated, as an ISO 8601 timestamp

Example:

"2026-01-15T09:30:00.000Z"

due_date
string

When the task is due, as an ISO 8601 UTC timestamp. null when no due date is set.

Example:

"2026-01-20T17:00:00.000Z"

remind_at
string

When a reminder for the task fires, as an ISO 8601 UTC timestamp. null when no reminder is set.

Example:

"2026-01-20T09:00:00.000Z"

notes
string

Free-form notes on the task. null when none were set.

Example:

"Customer prefers a call after 3pm IST"

chat_id
string

Id of the chat the task is linked to (directly, or through its message or ticket). null for todo tasks.

Example:

"120363000000000000@g.us"

association
object

The chat, message or ticket the task is linked to. null for todo tasks.

completed_metadata
object

Completion details, recorded when the task moves to status 'closed' and cleared when it is reopened. null while the task is open or inprogress.