REST API: Projects

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 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.

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