Tasks

The Tasks API provides a simple interface to manage tasks. The API allows you to create, delete and update your tasks. You can retrieve a single task, as well as list of all tasks.

A task can be either floating or related. Floating tasks are only associated with a user, whereas related tasks are associated with one of listed resources:

• Leads
• Contacts
• Deals

Parameters

Name	Read Only	Type	Description
id	true	number	Unique identifier of the task.
creator_id	true	number	Unique identifier of the user who created the task.
owner_id	false	number	Unique identifier of the user the task is assigned to.
resource_type	false	string	Name of the resource type the task is attached to. Possible values: lead, contact, deal
resource_id	false	number	Unique identifier of the resource the task is attached to.
completed	false	boolean	Indicator of whether the task is completed or not.
completed_at	true	string	Date and time of the task's completion in UTC (ISO8601 format).
due_date	false	string	Date and time of creation in UTC (ISO8601 format).
overdue	true	boolean	Indicator for whether the task has passed the due_date or not.
remind_at	false	string	Date and time that we should send you a reminder in UTC (ISO8601 format).
content	false	string	Content of the task.
created_at	true	string	Date and time of task creation in UTC (ISO8601 format).
updated_at	true	string	Date and time of the last update to the task in UTC (ISO8601 format).

Retrieve all tasks

GET /v2/tasks

Returns all tasks available to the user, according to the parameters provided.

If you ask for tasks without any parameter provided Sell API will return you both floating and related tasks. Although you can narrow the search set to either of them via query parameters.

Parameters

Name	Required	Type	In	Description
page	false	number	Query	Page number to start from. Page numbering starts at 1 and omitting the page parameter will return the first page.
per_page	false	number	Query	Number of records to return per page. The default limit is 25 and the maximum number that can be returned is 100.
sort_by	false	string	Query	A field to sort by. The default ordering is ascending. If you want to change the sort order to descending, append :desc to the field e.g. sort_by=resource_type:desc. Possible values: resource_type, completed_at, due_date, created_at, updated_at
ids	false	string	Query	Comma-separated list of task IDs to be returned in a request.
creator_id	false	number	Query	Unique identifier of the user. Returns all tasks created by the user.
owner_id	false	number	Query	Unique identifier of the user. Returns all tasks owned by the user.
q	false	string	Query	A query string to search for. Performs a full text search on the content field.
type	false	string	Query	Type of tasks to search for. Possible values: floating, related
resource_type	false	string	Query	Name of the resource type to search for. Possible values: lead, contact, deal
resource_id	false	number	Query	Unique identifier of the resource that you're searching for.
completed	false	boolean	Query	Indicates whether the query will return tasks that are completed or not.
overdue	false	boolean	Query	Indicates whether the query will return tasks where the due_date parameter has been passed or not.
remind	false	boolean	Query	Indicates whether the query will return tasks with reminders or without reminders.

Allowed for

• Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/tasks?type=related&resource_type=leads&completed=true \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "items": [
    {
      "data": {
        "id": 1,
        "creator_id": 1,
        "owner_id": 1,
        "resource_type": "lead",
        "resource_id": 1,
        "completed": true,
        "completed_at": "2014-09-29T16:32:56Z",
        "due_date": "2014-09-28T16:32:56Z",
        "overdue": false,
        "remind_at": "2014-09-29T15:32:56Z",
        "content": "Contact Tom",
        "created_at": "2014-08-27T16:32:56Z",
        "updated_at": "2014-08-27T17:32:56Z"
      },
      "meta": {
        "type": "task"
      }
    }
  ],
  "meta": {
    "type": "collection",
    "count": 1,
    "links": {
      "self": "http://api.getbase.com/v2/tasks.json"
    }
  }
}

---

Create a task

POST /v2/tasks

Creates a new task. You can create either a floating task or create a related task and associate it with one of the resource types below:

• Leads
• Contacts
• Deals

The remind_at date must be set earlier than the due_date attribute. Note that while you can specify different timezones in datetime fields during task creation, this functionality is not supported in the Search API. The Search API does not permit the use of different timezones in tasks.

Parameters

Name	Required	Type	In	Description
content	true	string	Body	e.g. Contact Tom
due_date	false	string	Body	e.g. 2014-09-27T16:32:56Z
owner_id	false	number	Body	Defaults to the unique identifier of the user who created the task.
resource_type	false	string	Body	e.g. lead
resource_id	false	number	Body	e.g. 1
completed	false	boolean	Body	e.g. true
remind_at	false	string	Body	e.g. 2014-09-26T15:32:56Z

Allowed for

• Agents

Using cURL

curl -v -X POST https://api.getbase.com/v2/tasks \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
  "data": {
    "resource_type": "lead",
    "resource_id": 1,
    "due_date": "2014-09-27T16:32:56Z",
    "remind_at": "2014-09-26T15:32:56Z",
    "content": "Contact Tom"
  },
  "meta": {
    "type": "task"
  }
}'

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "data": {
    "id": 1,
    "creator_id": 1,
    "owner_id": 1,
    "resource_type": "lead",
    "resource_id": 1,
    "completed": true,
    "completed_at": "2014-09-29T16:32:56Z",
    "due_date": "2014-09-28T16:32:56Z",
    "overdue": false,
    "remind_at": "2014-09-29T15:32:56Z",
    "content": "Contact Tom",
    "created_at": "2014-08-27T16:32:56Z",
    "updated_at": "2014-08-27T17:32:56Z"
  },
  "meta": {
    "type": "task"
  }
}

---

Retrieve a single task

GET /v2/tasks/:id

Returns a single task available to the user according to the unique task ID provided. If the specified task does not exist, this query will return an error.

Parameters

Name	Required	Type	In	Description
id	true	number	Query	Unique identifier of the task.

Allowed for

• Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/tasks/1 \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "data": {
    "id": 1,
    "creator_id": 1,
    "owner_id": 1,
    "resource_type": "lead",
    "resource_id": 1,
    "completed": true,
    "completed_at": "2014-09-29T16:32:56Z",
    "due_date": "2014-09-28T16:32:56Z",
    "overdue": false,
    "remind_at": "2014-09-29T15:32:56Z",
    "content": "Contact Tom",
    "created_at": "2014-08-27T16:32:56Z",
    "updated_at": "2014-08-27T17:32:56Z"
  },
  "meta": {
    "type": "task"
  }
}

---

Update a task

PUT /v2/tasks/:id

Updates task information. If the specified task does not exist, this query will return an error.

Parameters

Name	Required	Type	In	Description
id	true	number	Query	Unique identifier of the task.
content	false	string	Body	e.g. Contact Tom
due_date	false	string	Body	e.g. 2014-09-27T16:32:56Z
owner_id	false	number	Body	e.g. 1
resource_type	false	string	Body	e.g. lead
resource_id	false	number	Body	e.g. 1
completed	false	boolean	Body	true
remind_at	false	string	Body	e.g. 2014-09-29T15:32:56Z

Allowed for

• Agents

Using cURL

curl -v -X PUT https://api.getbase.com/v2/tasks/1 \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
  "data": {
    "completed": false,
    "content": "Contact Tom and Rachel"
  }
}'

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "data": {
    "id": 1,
    "creator_id": 1,
    "owner_id": 1,
    "resource_type": "lead",
    "resource_id": 1,
    "completed": false,
    "completed_at": null,
    "due_date": "2014-09-28T16:32:56Z",
    "overdue": false,
    "remind_at": "2014-09-29T15:32:56Z",
    "content": "Contact Tom and Rachel",
    "created_at": "2014-08-27T16:32:56Z",
    "updated_at": "2014-08-27T17:32:56Z"
  },
  "meta": {
    "type": "task"
  }
}

---

Delete a task

DELETE /v2/tasks/:id

Delete an existing task. If the specified task does not exist, this query will return an error. This operation cannot be undone.

Parameters

Name	Required	Type	In	Description
id	true	number	Query	Unique identifier of the task.

Allowed for

• Agents

Using cURL

curl -v -X DELETE https://api.getbase.com/v2/tasks/1 \
-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 204 No Content