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