Tasks and reminders

Use the Tasks API to create and assign work, attach tasks to SalesBinder records, schedule reminders, and maintain a private reminder inbox.

All responses use Cache-Control: no-store. Task results are limited by the current user's permissions, assignment rules, and access to any linked record. No endpoint returns another user's reminder inbox.

The task object

Field	Type	Description
`id`	string	Unique task UUID.
`object`	string	Always `task`.
`title`	string	Task title.
`description`	string or null	Optional task description.
`status`	string	`open`, `completed`, or `cancelled`.
`version`	integer	Positive version used for optimistic concurrency.
`time_zone`	string	IANA time zone used for the task schedule.
`due_date`	string or null	Calendar due date in `YYYY-MM-DD` format.
`due_time`	string or null	Local due time in `HH:mm` format.
`due_at`	string or null	Exact UTC due timestamp when the task has a time.
`overdue_at`	string or null	UTC timestamp at which the task becomes overdue.
`created`	string or null	ISO 8601 creation timestamp.
`modified`	string or null	ISO 8601 update timestamp.
`completed_at`	string or null	ISO 8601 completion timestamp.
`assignee`	object	Assigned user's UUID, name, optional profile photo, and active state.
`reminder`	object or null	Current reminder occurrence, generation, status, and scheduled timestamp.
`record`	object or null	Authorized linked-record preview, or `{available:false}` when the link is no longer accessible.
`available_actions`	array	Actions currently available to the caller: `edit`, `complete`, `cancel`, or `reopen`.

Linked records can be customers, prospects, suppliers, inventory items, invoices, estimates, purchase orders, sales orders, stock transfers, or kits. Reading a linked preview also requires the corresponding resource read scope and current record access.

List tasks

GET/api/v3/tasks

Required scope: tasks:read

Returns tasks ordered by deadline and then UUID, with undated tasks last. The response uses a cursor-based {object, data, next_cursor} envelope. Continue with the same filters and returned cursor; restart pagination if the server rejects a cursor.

Query parameters

Parameter	Type	Required	Description
`status`	string	No	`open`, `completed`, or `cancelled`. Defaults to `open`.
`scope`	string	No	`mine`, `all`, or `recovery`. Defaults to `mine`; `all` and `recovery` require permission to manage all tasks.
`assignee`	string	No	Assignee user UUID.
`q`	string	No	Case-insensitive title search, up to 100 characters.
`record_type`	string	No	Linked record type. Must be supplied with `record_id`.
`record_id`	string	No	Linked record UUID. Requires its type, read scope, and current visibility.
`due_from`	string	No	Earliest stored due date in `YYYY-MM-DD` format.
`due_to`	string	No	Latest stored due date in `YYYY-MM-DD` format.
`limit`	integer	No	Results per page from 1 to 100. Defaults to 40.
`cursor`	string	No	Opaque continuation cursor from the previous response.

curl "https://yourbusiness.salesbinder.com/api/v3/tasks?status=open&scope=mine&limit=40" \
  --header "Authorization: Bearer YOUR_API_KEY"

Create a task

POST/api/v3/tasks

Required scope: tasks:write

An Idempotency-Key header is required. New tasks must use the open status.

Field	Type	Required	Description
`title`	string	Yes	Task title from 1 to 255 characters.
`description`	string or null	No	Optional task details.
`assignee_user_id`	string	No	Active user UUID. Assigning another user requires task-assignment permission.
`due_date`	string or null	No	Due date in `YYYY-MM-DD` format.
`due_time`	string or null	No	Due time in `HH:mm` format.
`time_zone`	string	No	IANA time zone. Cannot be combined with `time_zone_mode`.
`time_zone_mode`	string	No	Use `mine` or `assignee` to resolve the time zone on the server.
`reminder_at`	string or null	No	Future ISO 8601 timestamp with an explicit offset.
`record`	object or null	No	Linked record as `{type, id}`.

Date-only deadlines retain their calendar date and have no due_at. Exact deadlines include a UTC due_at. Sending null clears an optional value.

curl "https://yourbusiness.salesbinder.com/api/v3/tasks" \
  --request POST \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: create-task-2026-09-12-001" \
  --data '{
    "title": "Follow up on estimate",
    "due_date": "2026-09-15",
    "time_zone_mode": "mine",
    "record": {
      "type": "estimate",
      "id": "ca921960-6e70-46a2-ab62-b890c05d461b"
    }
  }'

Returns the created task with 201 Created.

Retrieve a task

GET/api/v3/tasks/{id}

Required scope: tasks:read

Returns the current task, its assignee and reminder details, authorized linked-record preview, and available actions. A missing or inaccessible task returns 404 resource_missing. When the task remains accessible but its linked record does not, record is returned as {available:false} without the former record name or UUID.

Update, complete, cancel, or reopen a task

PATCH/api/v3/tasks/{id}

Required scope: tasks:write

An Idempotency-Key header and the task's current positive integer version are required. Send only fields that should change. Writable fields match task creation, and status can transition the task to completed, cancelled, or open.

A stale version returns 409 task_conflict; retrieve the current task before intentionally retrying. Reopening a task does not restore an old reminder. Include a future reminder_at to schedule another reminder.

List task activity

GET/api/v3/tasks/{id}/activity

Required scope: tasks:read

Returns up to 40 activity events in descending task-version order. Each event includes the action, version, actor, timestamp, and names of changed fields without retaining historical copies of private task text. Continue with before_version set to the response's next_before_version value.

Retrieve task statistics

GET/api/v3/tasks/stats

Required scope: tasks:read

Returns open, completed, overdue, and current-week counts for the requested scope. The optional record_type and record_id filters must be supplied together and require access to that linked record. Record-filtered responses echo the normalized record identity.

The response also includes task_badge_count: open tasks assigned to the caller that are due today or overdue. This personal total is independent of scope, record filters, pagination, and reminder occurrences.

List eligible assignees

GET/api/v3/tasks/assignees

Required scope: tasks:read

Returns eligible user UUIDs mapped to display names. A user without task-assignment permission receives only their own eligible entry.

Reconcile cached tasks

POST/api/v3/tasks/reconcile

Required scope: tasks:read

Send up to 100 known task IDs and versions. The response returns current authorized task objects in data and caller-supplied IDs that are no longer accessible in removed_ids.

{
  "known": [
    {
      "id": "b1823c6b-7269-4b99-9dc9-77daeb8541a1",
      "version": 3
    }
  ]
}

This read-only endpoint does not require an idempotency key. It returns current objects even when their versions match because user photos and linked-record permissions can change independently. Use task-list pagination to discover new tasks; reconciliation is for refreshing known entries.

List personal reminders

GET/api/v3/tasks/reminders

Required scope: tasks:read

Returns the caller's reminder occurrences in {object, data, unread_count, next_cursor}. Pages contain at most 40 reminders. Use cursor to continue. Fetching a reminder does not mark it as read.

Act on a reminder

POST/api/v3/tasks/reminders/{id}/{operation}

Required scope: tasks:write

Supported operations are read, dismiss, snooze, and complete. An Idempotency-Key header is required.

Operation	Request body
`read`	`{}`
`dismiss`	`{}`
`snooze`	Current task `version` and `minutes` set to `5`, `15`, `60`, or `1440`.
`complete`	Current task `version`.

Only the addressed reminder recipient can act on it. Snoozing creates a new reminder generation while preserving the task's due date. Refresh both the task and reminder inbox after a successful action.

Permissions and retry behavior

Task reads require tasks:read; creation, updates, and reminder actions require tasks:write. Live SalesBinder permissions still control managing all tasks, assigning other users, and accessing linked records.

For an uncertain write retry, reuse the same Idempotency-Key with the exact same request. The key provides short-lived replay protection; task versions independently prevent stale updates. After a prolonged or ambiguous create request, search or reconcile before submitting a different key that could create a duplicate.