Task

post

https://api.marketcircle.net/v1/tasks

Create a new task

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

See Task for a list of attributes which are supported for tasks. Only attributes marked as Read-Write can be set using this endpoint.

Ownership

The creator of the task will automatically be set to the user performing the request. However, a task also has an owner, which is the user responsible for the task. It defaults to the user making the request. See the ownership page for more details.

Response

A successful request returns 201 Created with the new task's reference, e.g. {"location": "/v1/tasks/1000"}. If validation fails, the response is 400 with the errors for each attribute, e.g. {"title": [{"error": "blank"}]}.

Body Params

title

string

Title (max 512 characters). Required.

details

string

Details (max 2048 characters).

category

string

Category name. Created if it does not exist. Send null or "" to clear.

keywords

array of strings

List of keyword names (max 64). Keywords that do not exist are created. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

keywords

due

date-time

Due date, e.g. 2025-03-31T17:00:00.000Z.

location

string

Location (max 2048 characters).

type

string

enum

Task type. Defaults to todo.

Allowed:

status

string

enum

Task status. Defaults to open.

Allowed:

priority

string

enum

Task priority. Defaults to no_priority.

Allowed:

started

date-time

When the task was started. Must not be after completed.

completed

date-time

When the task was completed.

estimated_time

integer

Estimated time in seconds.

subtasks

array of strings

References of tasks to make subtasks of this task, e.g. {"add": ["/v1/tasks/2001"]} (max 32 subtasks, nested at most 5 levels deep). To detach a subtask, set that task's parent_task to null.

subtasks

parent_task

string

Reference of the parent task, e.g. /v1/tasks/1001. Send null to make this a top-level task. If the parent is done, this task is marked done too.

appointments

array of objects

Appointments linked to the task. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

appointments

contacts

array of objects

Contacts linked to the task. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

contacts

companies

array of objects

Companies linked to the task. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

companies

opportunities

array of objects

Opportunities linked to the task. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

opportunities

projects

array of objects

Projects linked to the task. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

projects

groups

array of objects

Groups linked to the task. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

groups

notes

array of objects

Notes linked to the task. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

notes

forms

array of objects

Forms linked to the task. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

forms

email_messages

array of objects

Emails to link to the task. Write-only: use GET /v1/tasks/{id}/emails to list them. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

email_messages

owner

string

Reference to the user responsible for the task, e.g. /v1/users/1000. Defaults to the user making the request.

Responses

Ownership

Response

201201 Created

400400 Bad Request