The Project object

Property	Description	Editable
id	Vitally's unique ID for the Project	No
createdAt	Datetime the Project was created	No
name	The name of the project	Yes
accountId	The ID of the Vitally Account the Project is for	Only on create
organizationId	The ID of the Vitally Organization the Project is for	Only on create
templateId	The ID of the Vitally Project Template to create the Project from	Only on create
durationInDays	The number of days between the project's start date and its completion date. If the project is not completed yet, then the current date is used.	No
targetStartDate	The date the Project is targeted to start	Yes
actualStartDate	The date the Project was actually started	In-app
targetCompletionDate	The date the Project is targeted to complete	Yes
actualCompletionDate	The date the Project was actually completed	In-app
ownedByVitallyUserId	The ID of the Vitally Admin who owns the Project	Yes
projectCategoryId	The ID of the Vitally Project Category the Project belongs to	Yes
projectStatusId	The ID of the Vitally Project Status the Project belongs to	Yes
archivedAt	Datetime the Project was deleted	Set when projects are deleted
traits	A key-value JSON object of custom project traits. See below for more details.	Yes

The Project Category object

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

The Project Status object

Property	Description	Editable
id	Vitally's unique ID for the Project Status	No
createdAt	Datetime the Project Status was created	No
type	The type of Project Status. One of `active`, `inactive`, or `complete`	In-app
name	The name of the Project Status	In-app

Project custom traits

In Vitally, if you are an admin, you can add additional fields to your projects 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/projects
{
  "templateId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "traits": {
    "vitally.custom.nextStep": "Give em a call!"
  }
}

Example Response

{  
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "Project name",
  "durationInDays": 7,
  "ownedByVitallyUserId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "targetStartDate": "2021-01-01",
  "actualStartDate": null,
  "actualCompletionDate": null,
  "projectStatusId": null,
  "projectCategoryId": null,
  "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 project (i.e. the value for the trait will remain unchanged). To actually delete a trait from a project, 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 Projects `GET`

US Data Center (default):

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

EU Data Center:

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

Paginated list of Projects, 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/projects?limit=10&from=cursor

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

Example Response

{
  "results": [
    {
      "name": "Onboarding @ Acme",
      "createdAt": "2020-12-11T20:16:27.370Z",
      "ownedByVitallyUserId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "projectStatusId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "targetStartDate": "2020-12-29",
      "durationInDays": 7
    }
  ],
  "next": "c29tZWJhc2U2NA=="
}

List Projects For An Account `GET`

US Data Center (default):

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

EU Data Center:

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

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

Query Params (see Pagination)

Example Request

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

List Projects For An Organization `GET`

US Data Center (default):

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

EU Data Center:

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

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

Query Params (see Pagination)

Example Request

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

Create A Project from a template `POST`

Note that this API can only create Projects from a Project Template. It cannot create a Project from scratch (i.e. without a template).

US Data Center (default):

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

EU Data Center:

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

Request Body

Property	Type	Description
templateId	`string`	Required The Vitally ID of the Project Template to create the Project from
accountId	`string`	Required (if organizationId is not specified) The Vitally ID of the Vitally Account to associate the Project with
organizationId	`string`	Required (if accountId is not specified) The Vitally ID of the Vitally Organization to associate the Project with.
targetStartDate	`string`	The targeted date the Project should start by. If omitted, the Project will use the settings on the Project Template.
targetCompletionDate	`string`	The targeted date the Project should be completed by. If omitted, the Project will use the settings on the Project Template.
projectStatusId	`string`	The Vitally ID of the Project Status. If omitted, the default Project Status will be used
projectCategoryId	`string`	The Vitally ID of the Project Category. If omitted, the Project will use the settings on the Project Template.
ownedByVitallyUserId	`string`	The Vitally ID of the team member to own the Project. If omitted, the Project will use the settings on the Project Template.
name	`string`	The name of the Project. If omitted, the Project will use the settings on the Project Template.
traits	`key/value object`	A key-value JSON object of custom project traits. See above for more details.

Example Request

POST https://{subdomain}.rest.vitally.io/resources/projects
{
  "name": "Name that will be used over the Project Template",
  "templateId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "ownedByVitallyUserId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
}

Example Response

{  
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "accountId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "name": "Name that will be used over the Project Template",
  "durationInDays": 0,
  "ownedByVitallyUserId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "targetStartDate": null,
  "actualStartDate": null,
  "actualCompletionDate": null,
  "projectStatusId": null,
  "projectCategoryId": null,
  "traits": {},
}

Get A Project `GET`

US Data Center (default):

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

EU Data Center:

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

Request Params

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

Update A Project `PUT`

US Data Center (default):

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

EU Data Center:

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

Request Params

Property	Type	Description
id	`string`	The Vitally Project ID

Request Body

Property	Type	Description
targetStartDate	`string`	The targeted date the Project should start by.
targetCompletionDate	`string`	The targeted date the Project should be completed by.
projectStatusId	`string`	The Vitally ID of the Project Status
projectCategoryId	`string`	The Vitally ID of the Project Category.
ownedByVitallyUserId	`string`	The Vitally ID of the team member to own the Project.
name	`string`	The name of the Project.
traits	`key/value object`	A key-value JSON object of custom project traits. See above for more details.

Delete A Project `DELETE`

US Data Center (default):

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

EU Data Center:

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

Request Params

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

Project–Task Links

Tasks can be linked to or unlinked from a Project via dedicated endpoints. Linking places the Task on the Project's default milestone unless a named milestone is specified.

Link a Task to a Project `POST`

US Data Center (default):

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

EU Data Center:

https://rest.vitally-eu.io/resources/projects/:projectId/tasks/:taskId

Request Params

Property	Type	Description
projectId	`string`	Vitally Project ID (UUID)
taskId	`string`	Vitally Task ID (UUID) or Task `externalId` (with `source`)

Query Params

Param	Type	Description
source	`string`	(Optional) Integration name for Task `externalId` resolution

Request Body (optional JSON)

Property	Type	Description
milestone	`string`	(Optional) Exact milestone name on this Project. If set, places or moves the Task to that milestone. If omitted and the Task is not yet linked, it is added to the Project's default milestone.

Response

HTTP	Body	Meaning
201	`{ "created": true }`	New link created
200	`{ "created": false }`	Already linked, or moved to a different milestone

Errors: 404 if the Project, Task, or specified milestone is not found. 400 if the Task and Project Account/Organization alignment fails.

Example Request

POST https://{subdomain}.rest.vitally.io/resources/projects/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/tasks/yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy Content-Type: application/json { "milestone": "Onboarding" }

Example Response

{ "created": true }

Unlink a Task from a Project `DELETE`

Request Params and Query Params match the POST above. Returns 204 on success. Does not archive the Task itself — only removes the Project association. 404 if the Task is not linked to this Project.

REST API: Users

REST API: Notes

REST API: Tasks

REST API: NPS Responses

REST API: Project Templates

REST API: Projects

The Project object

The Project Category object

The Project Status object

Project custom traits

List Projects GET

List Projects For An Account GET

List Projects For An Organization GET

Create A Project from a template POST

Get A Project GET

Update A Project PUT

Delete A Project DELETE

Project–Task Links

Link a Task to a Project POST

Unlink a Task from a Project DELETE

List Projects `GET`

List Projects For An Account `GET`

List Projects For An Organization `GET`

Create A Project from a template `POST`

Get A Project `GET`

Update A Project `PUT`

Delete A Project `DELETE`

Link a Task to a Project `POST`

Unlink a Task from a Project `DELETE`