Tasks

The to-dos on the Tasks page: due dates, reminders, assignees, and links to contacts and opportunities.

Every route takes Authorization: Bearer <ACCESS_TOKEN> unless the auth line says otherwise. Ids are numbers. Errors use the shape on the errors page.

Route	Scope	What it does
`GET /v1/tasks`	`tasks.read`	A workspace's tasks, soonest due first.
`GET /v1/tasks/{id}`	`tasks.read`	One task.
`POST /v1/tasks`	`tasks.write`	Add a task to a workspace.
`PATCH /v1/tasks/{id}`	`tasks.write`	Change any of its fields.
`POST /v1/tasks/{id}/complete`	`tasks.write`	Mark it done.
`POST /v1/tasks/{id}/reopen`	`tasks.write`	Mark a completed task open again.
`DELETE /v1/tasks/{id}`	`tasks.write`	Delete it for good.

List tasks

GET https://api.bluereacher.com/v1/tasks

Auth: Bearer access token. Scope: tasks.read.

A workspace's tasks, soonest due first.

Open tasks by default. Undated tasks come after dated ones.

bucket gives the same groups as the Tasks page: overdue, today, upcoming and no_due (open tasks only; "today" is the UTC day).

Parameters

Name	In	Type	Required	Description
`workspace_id`	query	number	yes	The workspace.
`status`	query	enum	no	Default open.
`bucket`	query	enum	no	Overrides status.
`assignee_id`	query	number	no	Only tasks assigned to this team member.
`contact_id`	query	number	no	Only this contact's tasks.
`opportunity_id`	query	number	no	Only this opportunity's tasks.
`search`	query	string	no	Matches the title.
`page`	query	number	no	Default 1.
`limit`	query	number	no	1–100, default 25. Anything else is a 400.

Request

curl -X GET "https://api.bluereacher.com/v1/tasks?workspace_id=7&page=1&limit=25" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "data": [
    {
      "id": 300,
      "workspace_id": 7,
      "title": "Call Ann back about the quote",
      "description": null,
      "priority": "high",
      "status": "open",
      "due_at": "2026-11-03T09:00:00.000Z",
      "reminder_minutes_before": 15,
      "reminder_at": "2026-11-03T08:45:00.000Z",
      "assignee_id": 41,
      "contact_id": 1234,
      "contact": {
        "id": 1234,
        "first_name": "Ann",
        "last_name": "Lee",
        "email": "ann@example.com",
        "phone_number": "+61412345678",
        "company_name": "Lee Studio"
      },
      "opportunity_id": null,
      "opportunity": null,
      "completed_at": null,
      "created_at": "2026-10-27T09:00:00.000Z",
      "updated_at": "2026-10-27T09:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 25,
    "max_limit": 100,
    "total": 1,
    "total_pages": 1
  }
}

Status	When	Message
200	OK
400	workspace_id missing, or a bad status / bucket	`workspace_id is required`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): tasks.read. This integration was granted: …`
404	workspace_id does not exist or is not owned by the installer (same response for both)	`Workspace not found or not accessible to this token`

Response fields

task: Each item in data. Fields:

Field	Type	Description
`id`	number	Task id. Example: `300`
`workspace_id`	number	The workspace it belongs to. Example: `7`
`title`	string	What has to be done.
`description`	string, nullable	Details.
`priority`	string	"low", "medium" or "high". Example: `medium`
`status`	string	"open" or "completed". Example: `open`
`due_at`	string (ISO 8601), nullable	When it is due, UTC.
`reminder_minutes_before`	number, nullable	Minutes before due_at the assignee is reminded.
`reminder_at`	string (ISO 8601), nullable	When the reminder goes out (worked out from the two above).
`assignee_id`	number, nullable	The team member it is assigned to — the account owner or one of its subaccount admins.
`contact`	object, nullable	The linked contact: id, first_name, last_name, email, phone_number, company_name.
`opportunity`	object, nullable	The linked opportunity: id, name, status.
`completed_at`	string (ISO 8601), nullable	When it was completed.

Get task

GET https://api.bluereacher.com/v1/tasks/{id}

Auth: Bearer access token. Scope: tasks.read.

One task.

Parameters

Name	In	Type	Required	Description
`id`	path	number	yes	Task id.

Request

curl -X GET "https://api.bluereacher.com/v1/tasks/300" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "data": {
    "id": 300,
    "workspace_id": 7,
    "title": "Call Ann back about the quote",
    "description": null,
    "priority": "high",
    "status": "open",
    "due_at": "2026-11-03T09:00:00.000Z",
    "reminder_minutes_before": 15,
    "reminder_at": "2026-11-03T08:45:00.000Z",
    "assignee_id": 41,
    "contact_id": 1234,
    "contact": {
      "id": 1234,
      "first_name": "Ann",
      "last_name": "Lee",
      "email": "ann@example.com",
      "phone_number": "+61412345678",
      "company_name": "Lee Studio"
    },
    "opportunity_id": null,
    "opportunity": null,
    "completed_at": null,
    "created_at": "2026-10-27T09:00:00.000Z",
    "updated_at": "2026-10-27T09:00:00.000Z"
  }
}

Status	When	Message
200	OK
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): tasks.read. This integration was granted: …`
404	Task does not exist or is not in a workspace of the installer	`Task not found or not accessible to this token`

Response fields

task. Fields:

Field	Type	Description
`id`	number	Task id. Example: `300`
`workspace_id`	number	The workspace it belongs to. Example: `7`
`title`	string	What has to be done.
`description`	string, nullable	Details.
`priority`	string	"low", "medium" or "high". Example: `medium`
`status`	string	"open" or "completed". Example: `open`
`due_at`	string (ISO 8601), nullable	When it is due, UTC.
`reminder_minutes_before`	number, nullable	Minutes before due_at the assignee is reminded.
`reminder_at`	string (ISO 8601), nullable	When the reminder goes out (worked out from the two above).
`assignee_id`	number, nullable	The team member it is assigned to — the account owner or one of its subaccount admins.
`contact`	object, nullable	The linked contact: id, first_name, last_name, email, phone_number, company_name.
`opportunity`	object, nullable	The linked opportunity: id, name, status.
`completed_at`	string (ISO 8601), nullable	When it was completed.

Create task

POST https://api.bluereacher.com/v1/tasks

Auth: Bearer access token. Scope: tasks.write.

Add a task to a workspace.

With a due_at and reminder_minutes_before, the assignee (or the account owner) gets the same reminder as for a task made on the dashboard.

Parameters

Name	In	Type	Required	Description
`workspace_id`	body	number	yes	The workspace.
`title`	body	string	yes	Up to 255 characters.
`description`	body	string	no	Details, up to 5000 characters.
`priority`	body	enum	no	Default medium.
`due_at`	body	string	no	ISO 8601. null for no due date.
`reminder_minutes_before`	body	number	no	0–43200. Needs a due_at. null for no reminder.
`assignee_id`	body	number	no	The account owner, or a subaccount admin id from List subaccount admins. null to unassign.
`contact_id`	body	number	no	A contact in the same workspace. null to unlink.
`opportunity_id`	body	number	no	An opportunity in the same workspace. null to unlink.

Request

curl -X POST "https://api.bluereacher.com/v1/tasks" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "workspace_id": 7,
  "title": "Call Ann back about the quote",
  "priority": "high",
  "due_at": "2026-11-03T09:00:00Z",
  "reminder_minutes_before": 15,
  "assignee_id": 41,
  "contact_id": 1234
}'

Responses

A 201 reply (Created):

{
  "success": true,
  "message": "Task created",
  "data": {
    "id": 300,
    "workspace_id": 7,
    "title": "Call Ann back about the quote",
    "description": null,
    "priority": "high",
    "status": "open",
    "due_at": "2026-11-03T09:00:00.000Z",
    "reminder_minutes_before": 15,
    "reminder_at": "2026-11-03T08:45:00.000Z",
    "assignee_id": 41,
    "contact_id": 1234,
    "contact": {
      "id": 1234,
      "first_name": "Ann",
      "last_name": "Lee",
      "email": "ann@example.com",
      "phone_number": "+61412345678",
      "company_name": "Lee Studio"
    },
    "opportunity_id": null,
    "opportunity": null,
    "completed_at": null,
    "created_at": "2026-10-27T09:00:00.000Z",
    "updated_at": "2026-10-27T09:00:00.000Z"
  }
}

Status	When	Message
201	Created
400	Missing or invalid field	`priority must be one of: low, medium, high`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): tasks.write. This integration was granted: …`
404	workspace_id does not exist or is not owned by the installer (same response for both)	`Workspace not found or not accessible to this token`

Response fields

task. Fields:

Field	Type	Description
`id`	number	Task id. Example: `300`
`workspace_id`	number	The workspace it belongs to. Example: `7`
`title`	string	What has to be done.
`description`	string, nullable	Details.
`priority`	string	"low", "medium" or "high". Example: `medium`
`status`	string	"open" or "completed". Example: `open`
`due_at`	string (ISO 8601), nullable	When it is due, UTC.
`reminder_minutes_before`	number, nullable	Minutes before due_at the assignee is reminded.
`reminder_at`	string (ISO 8601), nullable	When the reminder goes out (worked out from the two above).
`assignee_id`	number, nullable	The team member it is assigned to — the account owner or one of its subaccount admins.
`contact`	object, nullable	The linked contact: id, first_name, last_name, email, phone_number, company_name.
`opportunity`	object, nullable	The linked opportunity: id, name, status.
`completed_at`	string (ISO 8601), nullable	When it was completed.

Update task

PATCH https://api.bluereacher.com/v1/tasks/{id}

Auth: Bearer access token. Scope: tasks.write.

Change any of its fields.

Send only what changes. Changing due_at or reminder_minutes_before sets the reminder again. To complete or reopen, use the endpoints below.

Parameters

Name	In	Type	Required	Description
`id`	path	number	yes	Task id.
`title`	body	string	no	Up to 255 characters.
`description`	body	string	no	Details, up to 5000 characters.
`priority`	body	enum	no	Default medium.
`due_at`	body	string	no	ISO 8601. null for no due date.
`reminder_minutes_before`	body	number	no	0–43200. Needs a due_at. null for no reminder.
`assignee_id`	body	number	no	The account owner, or a subaccount admin id from List subaccount admins. null to unassign.
`contact_id`	body	number	no	A contact in the same workspace. null to unlink.
`opportunity_id`	body	number	no	An opportunity in the same workspace. null to unlink.

Request

curl -X PATCH "https://api.bluereacher.com/v1/tasks/300" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "due_at": "2026-11-04T09:00:00Z",
  "priority": "medium"
}'

Responses

A 200 reply (OK):

{
  "success": true,
  "message": "Task updated",
  "data": {
    "id": 300,
    "workspace_id": 7,
    "title": "Call Ann back about the quote",
    "description": null,
    "priority": "medium",
    "status": "open",
    "due_at": "2026-11-04T09:00:00.000Z",
    "reminder_minutes_before": 15,
    "reminder_at": "2026-11-04T08:45:00.000Z",
    "assignee_id": 41,
    "contact_id": 1234,
    "contact": {
      "id": 1234,
      "first_name": "Ann",
      "last_name": "Lee",
      "email": "ann@example.com",
      "phone_number": "+61412345678",
      "company_name": "Lee Studio"
    },
    "opportunity_id": null,
    "opportunity": null,
    "completed_at": null,
    "created_at": "2026-10-27T09:00:00.000Z",
    "updated_at": "2026-10-27T09:00:00.000Z"
  }
}

Status	When	Message
200	OK
400	Nothing to update, or an invalid field	`assignee_id must be a member of this account`
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): tasks.write. This integration was granted: …`
404	Task does not exist or is not in a workspace of the installer	`Task not found or not accessible to this token`

Response fields

task. Fields:

Field	Type	Description
`id`	number	Task id. Example: `300`
`workspace_id`	number	The workspace it belongs to. Example: `7`
`title`	string	What has to be done.
`description`	string, nullable	Details.
`priority`	string	"low", "medium" or "high". Example: `medium`
`status`	string	"open" or "completed". Example: `open`
`due_at`	string (ISO 8601), nullable	When it is due, UTC.
`reminder_minutes_before`	number, nullable	Minutes before due_at the assignee is reminded.
`reminder_at`	string (ISO 8601), nullable	When the reminder goes out (worked out from the two above).
`assignee_id`	number, nullable	The team member it is assigned to — the account owner or one of its subaccount admins.
`contact`	object, nullable	The linked contact: id, first_name, last_name, email, phone_number, company_name.
`opportunity`	object, nullable	The linked opportunity: id, name, status.
`completed_at`	string (ISO 8601), nullable	When it was completed.

Complete task

POST https://api.bluereacher.com/v1/tasks/{id}/complete

Auth: Bearer access token. Scope: tasks.write.

Mark it done.

A reminder that has not gone out yet is cancelled.

Parameters

Name	In	Type	Required	Description
`id`	path	number	yes	Task id.

Request

curl -X POST "https://api.bluereacher.com/v1/tasks/300/complete" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "message": "Task completed",
  "data": {
    "id": 300,
    "workspace_id": 7,
    "title": "Call Ann back about the quote",
    "description": null,
    "priority": "high",
    "status": "completed",
    "due_at": "2026-11-03T09:00:00.000Z",
    "reminder_minutes_before": 15,
    "reminder_at": "2026-11-03T08:45:00.000Z",
    "assignee_id": 41,
    "contact_id": 1234,
    "contact": {
      "id": 1234,
      "first_name": "Ann",
      "last_name": "Lee",
      "email": "ann@example.com",
      "phone_number": "+61412345678",
      "company_name": "Lee Studio"
    },
    "opportunity_id": null,
    "opportunity": null,
    "completed_at": "2026-10-27T11:00:00.000Z",
    "created_at": "2026-10-27T09:00:00.000Z",
    "updated_at": "2026-10-27T09:00:00.000Z"
  }
}

Status	When	Message
200	OK
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): tasks.write. This integration was granted: …`
404	Task does not exist or is not in a workspace of the installer	`Task not found or not accessible to this token`

Response fields

task. Fields:

Field	Type	Description
`id`	number	Task id. Example: `300`
`workspace_id`	number	The workspace it belongs to. Example: `7`
`title`	string	What has to be done.
`description`	string, nullable	Details.
`priority`	string	"low", "medium" or "high". Example: `medium`
`status`	string	"open" or "completed". Example: `open`
`due_at`	string (ISO 8601), nullable	When it is due, UTC.
`reminder_minutes_before`	number, nullable	Minutes before due_at the assignee is reminded.
`reminder_at`	string (ISO 8601), nullable	When the reminder goes out (worked out from the two above).
`assignee_id`	number, nullable	The team member it is assigned to — the account owner or one of its subaccount admins.
`contact`	object, nullable	The linked contact: id, first_name, last_name, email, phone_number, company_name.
`opportunity`	object, nullable	The linked opportunity: id, name, status.
`completed_at`	string (ISO 8601), nullable	When it was completed.

Reopen task

POST https://api.bluereacher.com/v1/tasks/{id}/reopen

Auth: Bearer access token. Scope: tasks.write.

Mark a completed task open again.

Its reminder is set again when it is still in the future.

Parameters

Name	In	Type	Required	Description
`id`	path	number	yes	Task id.

Request

curl -X POST "https://api.bluereacher.com/v1/tasks/300/reopen" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

{
  "success": true,
  "message": "Task reopened",
  "data": {
    "id": 300,
    "workspace_id": 7,
    "title": "Call Ann back about the quote",
    "description": null,
    "priority": "high",
    "status": "open",
    "due_at": "2026-11-03T09:00:00.000Z",
    "reminder_minutes_before": 15,
    "reminder_at": "2026-11-03T08:45:00.000Z",
    "assignee_id": 41,
    "contact_id": 1234,
    "contact": {
      "id": 1234,
      "first_name": "Ann",
      "last_name": "Lee",
      "email": "ann@example.com",
      "phone_number": "+61412345678",
      "company_name": "Lee Studio"
    },
    "opportunity_id": null,
    "opportunity": null,
    "completed_at": null,
    "created_at": "2026-10-27T09:00:00.000Z",
    "updated_at": "2026-10-27T09:00:00.000Z"
  }
}

Status	When	Message
200	OK
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): tasks.write. This integration was granted: …`
404	Task does not exist or is not in a workspace of the installer	`Task not found or not accessible to this token`

Response fields

task. Fields:

Field	Type	Description
`id`	number	Task id. Example: `300`
`workspace_id`	number	The workspace it belongs to. Example: `7`
`title`	string	What has to be done.
`description`	string, nullable	Details.
`priority`	string	"low", "medium" or "high". Example: `medium`
`status`	string	"open" or "completed". Example: `open`
`due_at`	string (ISO 8601), nullable	When it is due, UTC.
`reminder_minutes_before`	number, nullable	Minutes before due_at the assignee is reminded.
`reminder_at`	string (ISO 8601), nullable	When the reminder goes out (worked out from the two above).
`assignee_id`	number, nullable	The team member it is assigned to — the account owner or one of its subaccount admins.
`contact`	object, nullable	The linked contact: id, first_name, last_name, email, phone_number, company_name.
`opportunity`	object, nullable	The linked opportunity: id, name, status.
`completed_at`	string (ISO 8601), nullable	When it was completed.

Delete task

DELETE https://api.bluereacher.com/v1/tasks/{id}

Auth: Bearer access token. Scope: tasks.write.

Delete it for good.

Parameters

Name	In	Type	Required	Description
`id`	path	number	yes	Task id.

Request

curl -X DELETE "https://api.bluereacher.com/v1/tasks/300" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Responses

A 200 reply (OK):

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

Status	When	Message
200	OK
401	Missing or invalid token	`Invalid or expired access token.`
403	Missing scope	`Missing scope(s): tasks.write. This integration was granted: …`
404	Task does not exist or is not in a workspace of the installer	`Task not found or not accessible to this token`

Tasks

On this page