Tasks

A task is an action item, often derived from a meeting. These endpoints list, search, create, update, complete and delete tasks.

Every endpoint below shows its parameters and response fields in the middle and a request sample with an example response on the right.

Base URL https://api.sally.ioVersion v1.0 current, not frozen yetHow versioning works

Lists the tasks of a directory (paginated, optionally filtered)

GET/v1.0/directories/{directoryId}/tasks

The ?filter selects a task view (default myTasks); the all* variants are admin/owner only. An optional ?search substring matches the task subject. Pagination via ?page + ?pageSize (max. 100). Resolve responsibleUserId/ownerId via GET /v1.0/directories/{directoryId}/memberships/users/{userId}.

Field overview from the specification

Response fields:

page / pageSize / total / hasMore: pagination envelope (current page, page size, total count, whether more pages follow).
items (array): the tasks on this page. Each item has:
- taskId (string): id of the task.
- subject (string): task subject.
- description (string | null): task description; null if unset.
- ownerId (string): id of the user who owns (created) the task.
- responsibleUserId (string | null): id of the user responsible for the task; null if unassigned.
- dueDate (string | null): due date (ISO 8601); null if no due date is set.
- isDone (boolean): whether the task is marked as done.
- doneOn (string | null): timestamp when the task was completed (ISO 8601); null if not done.
- isCanceled (boolean): whether the task is canceled.
- canceledOn (string | null): timestamp when the task was canceled (ISO 8601); null if not canceled.
- recordingSummaryId (string | null): id of the recording summary this task originated from; null if none.
- appointmentId (string | null): id of the appointment this task is linked to; null if none.
- createdOn (string): creation timestamp (ISO 8601).
- modifiedOn (string): last modification timestamp (ISO 8601).

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

Query parameters

filterstringoptional
Named preset that combines scope and state. my… covers the tasks of the calling user, all… every task of the directory the caller may see. The state part is Tasks (any), Open, Overdue, Completed or Forwarded. Omitted means no preset filter.
Allowed values: myTasksmyOpenmyOverduemyCompletedmyForwardedallTasksallOpenallOverdueallCompletedallForwarded
searchstringoptional
Case-insensitive substring match on the task subject. The term may appear at the start, middle, or end.
pagenumberoptional
Page number, 1-based. Defaults to 1.
pageSizenumberoptional
Items per page. Defaults to 25, capped at 100.
fieldsstringoptional
Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.
Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.
On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.
Selectable here: appointmentId, canceledOn, createdOn, description, doneOn, dueDate, isCanceled, isDone, modifiedOn, ownerId, recordingSummaryId, responsibleUserId, subject, taskId.
Example: appointmentId,canceledOn

Response: each entry in items

taskIdstringrequired
Id of the task.
subjectstringrequired
Task subject.
descriptionstringrequirednullable
Task description; null if unset.
ownerIdstringrequired
Id of the user who owns (created) the task.
responsibleUserIdstringrequirednullable
Id of the user responsible for the task; null if unassigned.
dueDatestringrequirednullable
Due date (ISO 8601); null if no due date is set.
isDonebooleanrequired
Whether the task is marked as done.
doneOnstringrequirednullable
Timestamp when the task was completed (ISO 8601); null if not done.
isCanceledbooleanrequired
Whether the task is canceled.
canceledOnstringrequirednullable
Timestamp when the task was canceled (ISO 8601); null if not canceled.
recordingSummaryIdstringrequirednullable
Id of the recording summary this task originated from; null if none.
appointmentIdstringrequirednullable
Id of the appointment this task is linked to; null if none.
createdOnstringrequired
Creation timestamp (ISO 8601).
modifiedOnstringrequired
Last modification timestamp (ISO 8601).

Every page also carries page, pageSize, total, hasMore.

Status codes

200Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Request

cURL
JavaScript
Python

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/tasks" \
  -H "Authorization: Bearer $SALLY_TOKEN"

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/tasks`, {
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    f"https://api.sally.io/v1.0/directories/{directory_id}/tasks",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
data = response.json()

Response example 200 OK

{
  "page": 1,
  "pageSize": 25,
  "total": 137,
  "hasMore": true,
  "items": [
    {
      "taskId": "6ceba541-fa71-44c7-a7f7-644d56b1b85d",
      "subject": "Quarterly planning",
      "description": "string",
      "ownerId": "e51b6a79-43bf-494f-a264-6825f41b0fb5",
      "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
      "dueDate": "2026-09-24T09:30:00Z",
      "isDone": true,
      "doneOn": "2026-09-24T09:30:00Z",
      "isCanceled": true,
      "canceledOn": "2026-09-24T09:30:00Z",
      "recordingSummaryId": "731180f9-257a-46cf-a7e3-8ca508fb9c35",
      "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
      "createdOn": "2026-09-24T09:30:00Z",
      "modifiedOn": "2026-09-24T09:30:00Z"
    }
  ]
}

Creates a task

POST/v1.0/directories/{directoryId}/tasks

Creates a task. The caller becomes the owner.

Field overview from the specification

Body fields:

subject (string, required): task subject (1..1000 characters).
description (string, optional): task description (max. 4000 characters); null for none.
responsibleUserId (string, optional): id of the responsible user; null or omitted leaves the task unassigned.
dueDate (string, optional): due date as an ISO 8601 string; null for no due date.

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

Query parameters

fieldsstringoptional
Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.
Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.
On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.
Selectable here: appointmentId, canceledOn, createdOn, description, doneOn, dueDate, isCanceled, isDone, modifiedOn, ownerId, recordingSummaryId, responsibleUserId, subject, taskId.
Example: appointmentId,canceledOn

Request body application/json

subjectstringrequired
Task subject (1..1000 characters).
descriptionstringoptionalnullable
Task description (max. 4000 characters); null for none.
responsibleUserIdstringoptionalnullable
Id of the responsible user; null for unassigned.
dueDatestringoptionalnullable
Due date as an ISO 8601 string; null for no due date.

Response

taskIdstringrequired
Id of the task.
subjectstringrequired
Task subject.
descriptionstringrequirednullable
Task description; null if unset.
ownerIdstringrequired
Id of the user who owns (created) the task.
responsibleUserIdstringrequirednullable
Id of the user responsible for the task; null if unassigned.
dueDatestringrequirednullable
Due date (ISO 8601); null if no due date is set.
isDonebooleanrequired
Whether the task is marked as done.
doneOnstringrequirednullable
Timestamp when the task was completed (ISO 8601); null if not done.
isCanceledbooleanrequired
Whether the task is canceled.
canceledOnstringrequirednullable
Timestamp when the task was canceled (ISO 8601); null if not canceled.
recordingSummaryIdstringrequirednullable
Id of the recording summary this task originated from; null if none.
appointmentIdstringrequirednullable
Id of the appointment this task is linked to; null if none.
createdOnstringrequired
Creation timestamp (ISO 8601).
modifiedOnstringrequired
Last modification timestamp (ISO 8601).

Status codes

200Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
403
Forbidden (insufficient permissions).
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Request

cURL
JavaScript
Python

curl -X POST "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/tasks" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Quarterly planning"
}'

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/tasks`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "subject": "Quarterly planning"
  }),
});
const data = await response.json();

import os
import requests

response = requests.post(
    f"https://api.sally.io/v1.0/directories/{directory_id}/tasks",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "subject": "Quarterly planning",
    },
)
data = response.json()

Response example 200 OK

{
  "taskId": "6ceba541-fa71-44c7-a7f7-644d56b1b85d",
  "subject": "Quarterly planning",
  "description": "string",
  "ownerId": "e51b6a79-43bf-494f-a264-6825f41b0fb5",
  "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
  "dueDate": "2026-09-24T09:30:00Z",
  "isDone": true,
  "doneOn": "2026-09-24T09:30:00Z",
  "isCanceled": true,
  "canceledOn": "2026-09-24T09:30:00Z",
  "recordingSummaryId": "731180f9-257a-46cf-a7e3-8ca508fb9c35",
  "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
  "createdOn": "2026-09-24T09:30:00Z",
  "modifiedOn": "2026-09-24T09:30:00Z"
}

Searches tasks (parameters in the body)

POST/v1.0/directories/{directoryId}/tasks/search

Searches tasks.

Field overview from the specification

Body fields:

search (string, optional): case-insensitive substring over the task subject AND description.
responsible (string, optional): filter by responsible user id — your own is always allowed, another user or omitting it (= all responsibles) requires admin/owner.
status (string, optional): one of open (not done/canceled), completed, overdue (open + past due), canceled; omit for any status.
page (number, optional, default 1): 1-based page number.
pageSize (number, optional, default 25): page size (max. 100).

Results are sorted by due date ascending.

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.

Query parameters

fieldsstringoptional
Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.
Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.
On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.
Selectable here: appointmentId, canceledOn, createdOn, description, doneOn, dueDate, isCanceled, isDone, modifiedOn, ownerId, recordingSummaryId, responsibleUserId, subject, taskId.
Example: appointmentId,canceledOn

Request body application/json

searchstringoptionalnullable
Case-insensitive substring match on the task subject AND description. The term may appear at the start, middle, or end.
responsiblestringoptionalnullable
Filter by responsible user id. Your own id is always allowed; another user or omitting it (= all responsibles) requires admin/owner.
statusstringoptionalnullable
Filter by status: open (not done/canceled), completed, overdue (open + past due), canceled. Omit for any status.
Allowed values: opencompletedoverduecanceled
pagenumberoptional
Page (1-based, default 1).
pageSizenumberoptional
Page size (default 25, max 100).

Response: each entry in items

taskIdstringrequired
Id of the task.
subjectstringrequired
Task subject.
descriptionstringrequirednullable
Task description; null if unset.
ownerIdstringrequired
Id of the user who owns (created) the task.
responsibleUserIdstringrequirednullable
Id of the user responsible for the task; null if unassigned.
dueDatestringrequirednullable
Due date (ISO 8601); null if no due date is set.
isDonebooleanrequired
Whether the task is marked as done.
doneOnstringrequirednullable
Timestamp when the task was completed (ISO 8601); null if not done.
isCanceledbooleanrequired
Whether the task is canceled.
canceledOnstringrequirednullable
Timestamp when the task was canceled (ISO 8601); null if not canceled.
recordingSummaryIdstringrequirednullable
Id of the recording summary this task originated from; null if none.
appointmentIdstringrequirednullable
Id of the appointment this task is linked to; null if none.
createdOnstringrequired
Creation timestamp (ISO 8601).
modifiedOnstringrequired
Last modification timestamp (ISO 8601).

Every page also carries page, pageSize, total, hasMore.

Status codes

200Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
403
Forbidden (insufficient permissions).
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Request

cURL
JavaScript
Python

curl -X POST "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/tasks/search" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "search": "pricing",
  "responsible": "string",
  "status": "open",
  "page": 1,
  "pageSize": 25
}'

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/tasks/search`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "search": "pricing",
    "responsible": "string",
    "status": "open",
    "page": 1,
    "pageSize": 25
  }),
});
const data = await response.json();

import os
import requests

response = requests.post(
    f"https://api.sally.io/v1.0/directories/{directory_id}/tasks/search",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "search": "pricing",
        "responsible": "string",
        "status": "open",
        "page": 1,
        "pageSize": 25,
    },
)
data = response.json()

Response example 200 OK

{
  "page": 1,
  "pageSize": 25,
  "total": 137,
  "hasMore": true,
  "items": [
    {
      "taskId": "6ceba541-fa71-44c7-a7f7-644d56b1b85d",
      "subject": "Quarterly planning",
      "description": "string",
      "ownerId": "e51b6a79-43bf-494f-a264-6825f41b0fb5",
      "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
      "dueDate": "2026-09-24T09:30:00Z",
      "isDone": true,
      "doneOn": "2026-09-24T09:30:00Z",
      "isCanceled": true,
      "canceledOn": "2026-09-24T09:30:00Z",
      "recordingSummaryId": "731180f9-257a-46cf-a7e3-8ca508fb9c35",
      "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
      "createdOn": "2026-09-24T09:30:00Z",
      "modifiedOn": "2026-09-24T09:30:00Z"
    }
  ]
}

Returns a single task by id

GET/v1.0/directories/{directoryId}/tasks/{taskId}

The caller must be allowed to view the task (owner, responsible, or admin/owner).

Field overview from the specification

Response fields:

taskId (string): id of the task.
subject (string): task subject.
description (string | null): task description; null if unset.
ownerId (string): id of the user who owns (created) the task.
responsibleUserId (string | null): id of the user responsible for the task; null if unassigned.
dueDate (string | null): due date (ISO 8601); null if no due date is set.
isDone (boolean): whether the task is marked as done.
doneOn (string | null): timestamp when the task was completed (ISO 8601); null if not done.
isCanceled (boolean): whether the task is canceled.
canceledOn (string | null): timestamp when the task was canceled (ISO 8601); null if not canceled.
recordingSummaryId (string | null): id of the recording summary this task originated from; null if none.
appointmentId (string | null): id of the appointment this task is linked to; null if none.
createdOn (string): creation timestamp (ISO 8601).
modifiedOn (string): last modification timestamp (ISO 8601).

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.
taskIdstringrequired
Id of the task.

Query parameters

fieldsstringoptional
Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.
Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.
On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.
Selectable here: appointmentId, canceledOn, createdOn, description, doneOn, dueDate, isCanceled, isDone, modifiedOn, ownerId, recordingSummaryId, responsibleUserId, subject, taskId.
Example: appointmentId,canceledOn

Response

taskIdstringrequired
Id of the task.
subjectstringrequired
Task subject.
descriptionstringrequirednullable
Task description; null if unset.
ownerIdstringrequired
Id of the user who owns (created) the task.
responsibleUserIdstringrequirednullable
Id of the user responsible for the task; null if unassigned.
dueDatestringrequirednullable
Due date (ISO 8601); null if no due date is set.
isDonebooleanrequired
Whether the task is marked as done.
doneOnstringrequirednullable
Timestamp when the task was completed (ISO 8601); null if not done.
isCanceledbooleanrequired
Whether the task is canceled.
canceledOnstringrequirednullable
Timestamp when the task was canceled (ISO 8601); null if not canceled.
recordingSummaryIdstringrequirednullable
Id of the recording summary this task originated from; null if none.
appointmentIdstringrequirednullable
Id of the appointment this task is linked to; null if none.
createdOnstringrequired
Creation timestamp (ISO 8601).
modifiedOnstringrequired
Last modification timestamp (ISO 8601).

Status codes

200Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Request

cURL
JavaScript
Python

curl "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/tasks/$TASK_ID" \
  -H "Authorization: Bearer $SALLY_TOKEN"

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/tasks/${taskId}`, {
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
const data = await response.json();

import os
import requests

response = requests.get(
    f"https://api.sally.io/v1.0/directories/{directory_id}/tasks/{task_id}",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
data = response.json()

Response example 200 OK

{
  "taskId": "6ceba541-fa71-44c7-a7f7-644d56b1b85d",
  "subject": "Quarterly planning",
  "description": "string",
  "ownerId": "e51b6a79-43bf-494f-a264-6825f41b0fb5",
  "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
  "dueDate": "2026-09-24T09:30:00Z",
  "isDone": true,
  "doneOn": "2026-09-24T09:30:00Z",
  "isCanceled": true,
  "canceledOn": "2026-09-24T09:30:00Z",
  "recordingSummaryId": "731180f9-257a-46cf-a7e3-8ca508fb9c35",
  "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
  "createdOn": "2026-09-24T09:30:00Z",
  "modifiedOn": "2026-09-24T09:30:00Z"
}

Updates a task (partial update)

PATCH/v1.0/directories/{directoryId}/tasks/{taskId}

Updates a task. Only the provided fields are changed; omitted fields keep their current value, a null value explicitly clears a field. The caller must be allowed to edit the task.

Field overview from the specification

Body fields:

subject (string, optional): new task subject (1..1000 characters).
description (string, optional): new task description (max. 4000 characters); null to clear.
responsibleUserId (string, optional): new id of the responsible user; null to unassign.
dueDate (string, optional): new due date as an ISO 8601 string; null to clear.

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.
taskIdstringrequired
Id of the task.

Query parameters

fieldsstringoptional
Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.
Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.
On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.
Selectable here: appointmentId, canceledOn, createdOn, description, doneOn, dueDate, isCanceled, isDone, modifiedOn, ownerId, recordingSummaryId, responsibleUserId, subject, taskId.
Example: appointmentId,canceledOn

Request body application/json

subjectstringoptional
New task subject (1..1000 characters).
descriptionstringoptionalnullable
New task description (max. 4000 characters); null to clear.
responsibleUserIdstringoptionalnullable
New id of the responsible user; null to unassign.
dueDatestringoptionalnullable
New due date as an ISO 8601 string; null to clear.

Response

taskIdstringrequired
Id of the task.
subjectstringrequired
Task subject.
descriptionstringrequirednullable
Task description; null if unset.
ownerIdstringrequired
Id of the user who owns (created) the task.
responsibleUserIdstringrequirednullable
Id of the user responsible for the task; null if unassigned.
dueDatestringrequirednullable
Due date (ISO 8601); null if no due date is set.
isDonebooleanrequired
Whether the task is marked as done.
doneOnstringrequirednullable
Timestamp when the task was completed (ISO 8601); null if not done.
isCanceledbooleanrequired
Whether the task is canceled.
canceledOnstringrequirednullable
Timestamp when the task was canceled (ISO 8601); null if not canceled.
recordingSummaryIdstringrequirednullable
Id of the recording summary this task originated from; null if none.
appointmentIdstringrequirednullable
Id of the appointment this task is linked to; null if none.
createdOnstringrequired
Creation timestamp (ISO 8601).
modifiedOnstringrequired
Last modification timestamp (ISO 8601).

Status codes

200Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
403
Forbidden (insufficient permissions).
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Request

cURL
JavaScript
Python

curl -X PATCH "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/tasks/$TASK_ID" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Quarterly planning",
  "description": "string",
  "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
  "dueDate": "2026-09-24T09:30:00Z"
}'

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/tasks/${taskId}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "subject": "Quarterly planning",
    "description": "string",
    "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
    "dueDate": "2026-09-24T09:30:00Z"
  }),
});
const data = await response.json();

import os
import requests

response = requests.patch(
    f"https://api.sally.io/v1.0/directories/{directory_id}/tasks/{task_id}",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "subject": "Quarterly planning",
        "description": "string",
        "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
        "dueDate": "2026-09-24T09:30:00Z",
    },
)
data = response.json()

Response example 200 OK

{
  "taskId": "6ceba541-fa71-44c7-a7f7-644d56b1b85d",
  "subject": "Quarterly planning",
  "description": "string",
  "ownerId": "e51b6a79-43bf-494f-a264-6825f41b0fb5",
  "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
  "dueDate": "2026-09-24T09:30:00Z",
  "isDone": true,
  "doneOn": "2026-09-24T09:30:00Z",
  "isCanceled": true,
  "canceledOn": "2026-09-24T09:30:00Z",
  "recordingSummaryId": "731180f9-257a-46cf-a7e3-8ca508fb9c35",
  "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
  "createdOn": "2026-09-24T09:30:00Z",
  "modifiedOn": "2026-09-24T09:30:00Z"
}

Deletes a task (soft-delete)

DELETE/v1.0/directories/{directoryId}/tasks/{taskId}

Only the owner or an admin/owner may delete a task.

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.
taskIdstringrequired
Id of the task.

Status codes

204Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
403
Forbidden (insufficient permissions).
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Request

cURL
JavaScript
Python

curl -X DELETE "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/tasks/$TASK_ID" \
  -H "Authorization: Bearer $SALLY_TOKEN"

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/tasks/${taskId}`, {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
  },
});
console.log(response.status); // 204

import os
import requests

response = requests.delete(
    f"https://api.sally.io/v1.0/directories/{directory_id}/tasks/{task_id}",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
)
print(response.status_code)  # 204

Response example 204 No Content

No content. A successful call returns an empty body.

Toggles the done status of a task

POST/v1.0/directories/{directoryId}/tasks/{taskId}/done

Toggles the done status of a task.

Field overview from the specification

Body fields:

isDone (boolean, required): true to mark the task as done, false to reopen it.

Path parameters

directoryIdstringrequired
Id of the directory (the Sally company account) the resource belongs to. The directories a token can address are listed by GET /v1.0/me/directories/memberships.
taskIdstringrequired
Id of the task.

Query parameters

fieldsstringoptional
Comma-separated list of the fields to return. Leave it out and you get every field — including fields added in the future, which is your call to make: name your fields if you want to be shielded from that.
Only first-level fields can be named. A nested list such as attendees, tags or sectionItems is returned whole or not at all; attendees.name is not supported.
On a paged response the selection applies to the entries in items; page, pageSize, total and hasMore are always returned. An unknown name is rejected with 400 rather than ignored.
Selectable here: appointmentId, canceledOn, createdOn, description, doneOn, dueDate, isCanceled, isDone, modifiedOn, ownerId, recordingSummaryId, responsibleUserId, subject, taskId.
Example: appointmentId,canceledOn

Request body application/json

isDonebooleanrequired
True to mark the task as done, false to reopen it.

Response

taskIdstringrequired
Id of the task.
subjectstringrequired
Task subject.
descriptionstringrequirednullable
Task description; null if unset.
ownerIdstringrequired
Id of the user who owns (created) the task.
responsibleUserIdstringrequirednullable
Id of the user responsible for the task; null if unassigned.
dueDatestringrequirednullable
Due date (ISO 8601); null if no due date is set.
isDonebooleanrequired
Whether the task is marked as done.
doneOnstringrequirednullable
Timestamp when the task was completed (ISO 8601); null if not done.
isCanceledbooleanrequired
Whether the task is canceled.
canceledOnstringrequirednullable
Timestamp when the task was canceled (ISO 8601); null if not canceled.
recordingSummaryIdstringrequirednullable
Id of the recording summary this task originated from; null if none.
appointmentIdstringrequirednullable
Id of the appointment this task is linked to; null if none.
createdOnstringrequired
Creation timestamp (ISO 8601).
modifiedOnstringrequired
Last modification timestamp (ISO 8601).

Status codes

200Success
400
Invalid request (validation error).
401
Missing or invalid bearer token.
403
Forbidden (insufficient permissions).
404
Resource not found or not accessible.
429
Rate limit exceeded (per token/IP). Transcription uploads may also return code FUP_LIMIT_EXCEEDED or TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
500
Internal server error.

Request

cURL
JavaScript
Python

curl -X POST "https://api.sally.io/v1.0/directories/$DIRECTORY_ID/tasks/$TASK_ID/done" \
  -H "Authorization: Bearer $SALLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "isDone": true
}'

const response = await fetch(`https://api.sally.io/v1.0/directories/${directoryId}/tasks/${taskId}/done`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SALLY_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "isDone": true
  }),
});
const data = await response.json();

import os
import requests

response = requests.post(
    f"https://api.sally.io/v1.0/directories/{directory_id}/tasks/{task_id}/done",
    headers={"Authorization": f"Bearer {os.environ['SALLY_TOKEN']}"},
    json={
        "isDone": True,
    },
)
data = response.json()

Response example 200 OK

{
  "taskId": "6ceba541-fa71-44c7-a7f7-644d56b1b85d",
  "subject": "Quarterly planning",
  "description": "string",
  "ownerId": "e51b6a79-43bf-494f-a264-6825f41b0fb5",
  "responsibleUserId": "1b84577d-c09e-446b-a5b8-71591dfde929",
  "dueDate": "2026-09-24T09:30:00Z",
  "isDone": true,
  "doneOn": "2026-09-24T09:30:00Z",
  "isCanceled": true,
  "canceledOn": "2026-09-24T09:30:00Z",
  "recordingSummaryId": "731180f9-257a-46cf-a7e3-8ca508fb9c35",
  "appointmentId": "d4398f97-cd92-4d21-a6ec-4aab0a85441b",
  "createdOn": "2026-09-24T09:30:00Z",
  "modifiedOn": "2026-09-24T09:30:00Z"
}

Lists the tasks of a directory (paginated, optionally filtered)​

Path parameters

Query parameters

Response: each entry in items

Status codes

Creates a task​

Path parameters

Query parameters

Request body application/json

Response

Status codes

Searches tasks (parameters in the body)​

Path parameters

Query parameters

Request body application/json

Response: each entry in items

Status codes

Returns a single task by id​

Path parameters

Query parameters

Response

Status codes

Updates a task (partial update)​

Path parameters

Query parameters

Request body application/json

Response

Status codes

Deletes a task (soft-delete)​

Path parameters

Status codes

Toggles the done status of a task​

Path parameters

Query parameters

Request body application/json

Response

Status codes

Lists the tasks of a directory (paginated, optionally filtered)

Creates a task

Searches tasks (parameters in the body)

Returns a single task by id

Updates a task (partial update)

Deletes a task (soft-delete)

Toggles the done status of a task