Comment on page

REST API: Tasks

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://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
https://rest.vitally.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://rest.vitally.io/resources/tasks?limit=10&from=cursor
GET https://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
https://rest.vitally.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://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
https://rest.vitally.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://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
https://rest.vitally.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://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
https://rest.vitally.io/resources/tasks/:id
Request Params
Property
Type
Description
id
string
The Task ID assigned by Vitally
Update A Task PUT
https://rest.vitally.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
https://rest.vitally.io/resources/tasks/:id
Request Params
Property
Type
Description
id
string
The Task ID assigned by Vitally
List A Task Categories GET
https://rest.vitally.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://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=="
}

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

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

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`

Property	Type	Description
id	`string`	The Task ID assigned by Vitally

Property	Type	Description
organizationId	`string`	The Organization ID assigned by Vitally

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.

Property	Type	Description
id	`string`	The Task ID assigned by Vitally

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

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.

Property	Type	Description
id	`string`	The Task ID assigned by Vitally

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

REST API: Projects

REST API: NPS Responses

Last modified 2d ago

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`