REST API: Tasks

Replace {subdomain} in the endpoints below with your Vitally subdomain.

You can find your subdomain in the URL used to log into Vitally (i.e., https://yoursubdomain.vitally.io

The Task object

Property	Description	Editable
id	Vitally's unique ID for the Task	No
createdAt	Datetime the Task was created	No
updatedAt	Datetime the Task was last updated	No
externalId	Your unique ID for the Task	Only on create
accountId	Required The ID of the Vitally Account the Task is for	Yes
organizationId	Required (when applicable) The ID of the Vitally Organization to associate the Task with.	Yes
name	Required The subject or title of the Task	Yes
description	The body of the Task, may include HTML (see HTML Fields)	Yes
dueDate	The date-time of when the Task is due	Yes
assignedToId	The ID of the Vitally Admin who is assigned to the Task	Yes
completedById	The ID of the Vitally Admin who completed to the Task	Yes
categoryId	The ID of the Vitally Task Category the Task belongs to	Yes
projects	An array of project IDs and names { id, name }[]	In-app
tags	An array of string tags to associate to the task	Yes
archivedAt	Datetime the Task was deleted	Set when tasks are deleted in-app or via DELETE endpoint
traits	A key-value JSON object of custom task traits. See below for more details.	Yes

The Task Category object

Property	Description	Editable
id	Vitally's unique ID for the task Category	No
createdAt	Datetime the Task Category was created	No
updatedAt	Datetime the Task Category was last updated	No
name	The name of the Task Category	In-app

Task custom traits

In Vitally, if you are an admin, you can add additional fields to your tasks via the Traits management section. When you create a trait, we will provide you with a key for that trait:

Using this key, you can set values for this trait when POSTing or PUTing to the API:

Example Request

POST https://{subdomain}.rest.vitally.io/resources/tasks
{
  "name": "Check in on the Account",
  "accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "externalId": "task-1",
  "description": "<p>Be sure to ask how onboarding is going.</p>",
  "assignedToId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "completedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "dueDate": "2021-01-01",
  "completedAt": "2020-12-29T20:16:27.370Z"
  "traits": {
    "vitally.custom.nextStep": "Give em a call!"
  }
}

Example Response

{  
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "externalId": "task-1",
  "accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "categoryId": null,
  "assignedToId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "completedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "Check in on the Account",
  "description": "<p>Be sure to ask how onboarding is going.</p>",
  "dueDate": "2021-01-01",
  "completedAt": "2020-12-29T20:16:27.370Z"
  "traits": {
    "vitally.custom.nextStep": "Give em a call!"
  }
}

Note that when updating traits, if a trait is not specified, it will not be deleted from the task (i.e. the value for the trait will remain unchanged). To actually delete a trait from a task, simply specify the trait with a null value.

List Tasks GET

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/tasks

EU Data Center:

https://rest.vitally-eu.io/resources/tasks

Paginated list of Tasks, by default ordered by updatedAt.

Query Params (see Pagination)

Param	Type	Description
limit	number	(optional) The number of items to return. The max/default is 100
from	string	(optional) The cursor returned from a previous request
archived	boolean	(optional) Show only deleted items if true, or only active items if false

Params (see Pagination)

Example Requests

GET https://{subdomain}.rest.vitally.io/resources/tasks?limit=10&from=cursor

GET https://{subdomain}.rest.vitally.io/resources/tasks?archived=true

Example Response

{
  "results": [
    {
      "externalId": "task-1",
      "name": "Check in on the Account",
      "description": "<p>Be sure to ask how onboarding is going.</p>",
      "createdAt": "2020-12-11T20:16:27.370Z",
      "updatedAt": "2020-12-11T20:16:27.370Z",
      "createdById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "assignedToId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "completedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "dueDate": "2021-01-01",
      "completedAt": "2020-12-29T20:16:27.370Z",
    }
  ],
  "next": "c29tZWJhc2U2NA=="
}

List Tasks For An Account GET

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/accounts/:accountId/tasks

EU Data Center:

https://rest.vitally-eu.io/resources/accounts/:accountId/tasks

Paginated list of Tasks for a given Account, by default ordered by updatedAt.

Request Params

Property	Type	Description
id	string	The Task ID assigned by Vitally

Query Params (see Pagination)

Example Request

GET https://{subdomain}.rest.vitally.io/resources/accounts/:accountId/tasks?limit=10&from=cursor

Example Response

{
  "results": [
    {
      "externalId": "task-1",
      "name": "Check in on the Account",
      "description": "<p>Be sure to ask how onboarding is going.</p>",
      "createdAt": "2020-12-11T20:16:27.370Z",
      "updatedAt": "2020-12-11T20:16:27.370Z",
      "createdById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "assignedToId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "completedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "dueDate": "2021-01-01",
      "completedAt": "2020-12-29T20:16:27.370Z",
    }
  ],
  "next": "c29tZWJhc2U2NA=="
}

List Tasks For An Organization GET

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/organizations/:organizationId/tasks

EU Data Center:

https://rest.vitally-eu.io/resources/organizations/:organizationId/tasks

Paginated list of Tasks for a given Organization, by default ordered by updatedAt.

Request Params

Property	Type	Description
organizationId	string	The Organization ID assigned by Vitally

Query Params (see Pagination)

Example Request

GET https://{subdomain}.rest.vitally.io/resources/organizations/:organizationId/tasks?limit=10&from=cursor

Example Response

{
  "results": [
    {
      "externalId": "task-1",
      "name": "Check in on the Organization",
      "description": "<p>Be sure to ask how onboarding is going.</p>",
      "createdAt": "2020-12-11T20:16:27.370Z",
      "updatedAt": "2020-12-11T20:16:27.370Z",
      "createdById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "assignedToId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "completedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "dueDate": "2021-01-01",
      "completedAt": "2020-12-29T20:16:27.370Z",
    }
  ],
  "next": "c29tZWJhc2U2NA=="
}

Create A Task POST

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/tasks

EU Data Center:

https://rest.vitally-eu.io/resources/tasks

Task's are unique on externalId. So creating and updating are both possible via the POST endpoint.

Request Body

Property	Type	Description
name	string	Required The name or subject of the Task
accountId	string	Required The ID of the Vitally Account to associate the Task with
organizationId	string	Required (if accountId is not specified) The ID of the Vitally Organization to associate the Task with.
externalId	string	The unique ID of the Task in your system
description	string	The description of the Task, may include HTML (see HTML Fields)
assignedToId	string	The ID of the Vitally Admin User who is assigned to the Task
completedById	string	The ID of the Vitally Admin User who completed to the Task
dueDate	string	The date when the Task is due
completedAt	string	The timestamp of when the Task was completed
categoryId	string	The Vitally ID of the Task Category
tags	array of strings	An array of string tags to associate to the note
traits	key/value object	A key-value JSON object of custom note traits. See above for more details.

Example Request

POST https://{subdomain}.rest.vitally.io/resources/tasks
{
  "name": "Check in on the Account",
  "accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "externalId": "task-1",
  "description": "<p>Be sure to ask how onboarding is going.</p>",
  "assignedToId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "completedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "dueDate": "2021-01-01",
  "completedAt": "2020-12-29T20:16:27.370Z"
}

Example Response

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "externalId": "task-1",
  "accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "categoryId": null,
  "assignedToId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "completedById": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "Check in on the Account",
  "description": "<p>Be sure to ask how onboarding is going.</p>",
  "dueDate": "2021-01-01",
  "completedAt": "2020-12-29T20:16:27.370Z"
}

Get A Task GET

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/tasks/:id

EU Data Center:

https://rest.vitally-eu.io/resources/tasks/:id

Request Params

Property	Type	Description
id	string	The Task ID assigned by Vitally

Update A Task PUT

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/tasks/:id

EU Data Center:

https://rest.vitally-eu.io/resources/tasks/:id

Request Params

Property	Type	Description
id	string	Accepts both the Task ID assigned by Vitally and the externalId if provided when creating the Task

Request Body

Property	Type	Description
name	string	The name or subject of the Task
accountId	string	The ID of the Vitally Account to associate the Task with
organizationId	string	Required (if accountId is not specified) The ID of the Vitally Organization to associate the Task with.
externalId	string	The unique ID of the Task in your system
description	string	The description of the Task, may include HTML (see HTML Fields)
assignedToId	string	The ID of the Vitally Admin User who is assigned to the Task
completedById	string	The ID of the Vitally Admin User who completed to the Task
dueDate	string	The date when the Task is due
completedAt	string	The timestamp of when the Task was completed
categoryId	string	The Vitally ID of the Task Category
tags	array of strings	An array of string tags to associate to the note
traits	key/value object	A key-value JSON object of custom note traits. See above for more details.

Delete A Task `DELETE

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/tasks/:id

EU Data Center:

https://rest.vitally-eu.io/resources/tasks/:id

Request Params

Property	Type	Description
id	string	The Task ID assigned by Vitally

List A Task Categories GET

US Data Center (default):

https://{subdomain}.rest.vitally.io/resources/taskCategories

EU Data Center:

https://rest.vitally-eu.io/resources/taskCategories

Paginated list of Task Categories.

Task Categories are managed in the Vitally UI. The ID of the Task Category is required for associating a Task with a Task Category via the Rest API.

Params (see Pagination)

Query Params

Param	Type	Description
limit	number	(optional) The number of items to return. The max/default is 100
from	string	(optional) The cursor returned from a previous request

Example Request

GET https://{subdomain}.rest.vitally.io/resources/taskCategories?limit=10&from=cursor

Example Response

{
  "results": [
    {
      "id": "xxxx-xxxxx-xxxxxxxx-xxxxxxxx",
      "name": "Onboarding",
      "createdAt": "2020-12-11T20:16:27.370Z",
      "updatedAt": "2020-12-11T20:16:27.370Z"
    },
    {
      "id": "xxxx-xxxxx-xxxxxxxx-xxxxxxxx",
      "name": "High Touch",
      "createdAt": "2020-12-11T20:16:27.370Z",
      "updatedAt": "2020-12-11T20:16:27.370Z"
    }
  ],
  "next": "c29tZWJhc2U2NA=="
}