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.

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

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=="
}

REST API: Conversations

REST API: Messages

REST API: Notes

REST API: Projects

REST API: NPS Responses

REST API: Tasks

The Task object

The Task Category object

Task custom traits

List Tasks GET

List Tasks For An Account GET

List Tasks For An Organization GET

Create A Task POST

Get A Task GET

Update A Task PUT

Delete A Task DELETE

List A Task Categories GET

List Tasks `GET`

List Tasks For An Account `GET`

List Tasks For An Organization `GET`

Create A Task `POST`

Get A Task `GET`

Update A Task `PUT`

Delete A Task `DELETE`

List A Task Categories `GET`