The Note object

Property	Description	Editable
id	Vitally's unique ID for the Note	No
createdAt	Datetime the Note was created	No
updatedAt	Datetime the Note was last updated	No
externalId	Your unique ID for the Note	Only on create
note	Required The body of the Note, may include HTML (see HTML Fields)	Yes
noteDate	Required The date-time of when the Note was created	Yes
subject	The subject or title of the Note	Yes
authorId	The ID of the Vitally Admin who created the Note	Yes
categoryId	The ID of the Vitally Note Category the Note belongs to	Yes
archivedAt	Datetime the Note was deleted	Set when notes are deleted in-app or via DELETE endpoint
tags	An array of string tags to associate to the note	Yes
traits	A key-value JSON object of custom note traits. See below for more details.	Yes

The Note Category object

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

Note custom traits

In Vitally, if you are an admin, you can add additional fields to your notes 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/notes
{
  "externalId": "note-1",
  "subject": "What's the deal with the Account",
  "note": "<p>Be sure to check in on them</p>",
  "noteDate": "2020-12-11T20:16:27.370Z",
  "authorId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "traits": {
    "vitally.custom.nextStep": "Give em a call!"
  }
}

Example Response

{
  "externalId": "note-1",
  "subject": "What's the deal with the Account",
  "note": "<p>Be sure to check in on them</p>",
  "noteDate": "2020-12-11T20:16:27.370Z",
  "authorId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "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 note (i.e. the value for the trait will remain unchanged). To actually delete a trait from a note, 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 Notes `GET`

US Data Center (default):

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

EU Data Center:

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

Paginated list of Notes, by default ordered by updatedAt.

Params (see Pagination)

Example Request

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

Example Response

{
  "results": [
    {
      "externalId": "note-1",
      "subject": "What's the deal with the Account",
      "note": "<p>Be sure to check in on them</p>",
      "noteDate": "2020-12-11T20:16:27.370Z",
      "authorId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ],
  "next": "c29tZWJhc2U2NA=="
}

List Notes For An Account `GET`

US Data Center (default):

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

EU Data Center:

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

Paginated list of Notes for a given Account, 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`

Example Requests

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

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

Example Response

{
  "results": [
    {
      "id": "xxxx-xxxxx-xxxxxxxx-xxxxxxxx",
      "externalId": "note-1",
      "subject": "What's the deal with the Account",
      "note": "<p>Be sure to check in on them</p>",
      "createdAt": "2020-12-11T20:16:27.370Z",
      "updatedAt": "2020-12-11T20:16:27.370Z",
      "authorId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ],
  "next": "c29tZWJhc2U2NA=="
}

List Notes For An Organization `GET`

US Data Center (default):

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

EU Data Center:

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

Paginated list of Notes for a given Organization, 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

Example Request

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

Example Response

{
  "results": [
    {
      "id": "xxxx-xxxxx-xxxxxxxx-xxxxxxxx",
      "externalId": "note-1",
      "subject": "What's the deal with the Organization",
      "note": "<p>Be sure to check in on them</p>",
      "createdAt": "2020-12-11T20:16:27.370Z",
      "updatedAt": "2020-12-11T20:16:27.370Z",
      "authorId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ],
  "next": "c29tZWJhc2U2NA=="
}

Create A Note `POST`

US Data Center (default):

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

EU Data Center:

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

Notes are unique on externalId.

Request Body

Property	Type	Description
accountId	`string`	Required The ID of the Vitally Account to associate the Note with. Not to be confused with an External ID, this is the Vitally Account ID
organizationId	`string`	Required (when applicable) The ID of the Vitally Organization to associate the Note with. Not to be confused with an External ID, this is the Vitally Organization ID
note	`string`	Required The body of the Note, may include HTML (see HTML Fields)
noteDate	`string`	Required The timestamp of when the Note was created
externalId	`string`	The unique ID of the Note in your system
subject	`string`	The subject or title of the Note
authorId	`string`	The ID of the Vitally User who created the Note
categoryId	`string`	The ID of the Vitally Note Category the Note belongs to
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/notes
{
  "externalId": "note-1",
  "subject": "What's the deal with the Account",
  "note": "<p>Be sure to check in on them</p>",
  "noteDate": "2020-12-11T20:16:27.370Z",
  "authorId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Example Response

{
  "externalId": "note-1",
  "subject": "What's the deal with the Account",
  "note": "<p>Be sure to check in on them</p>",
  "noteDate": "2020-12-11T20:16:27.370Z",
  "authorId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Get A Note `GET`

US Data Center (default):

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

EU Data Center:

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

Request Params

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

Update A Note `PUT`

US Data Center (default):

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

EU Data Center:

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

If you are updating an existing Note that already has tags, you'll need to include the tags array with every applied tag as a string in the PUT request. If you do not include the tags array in the PUT request, all tags will be removed from the Note.

Request Params

string

Accepts both the Note ID assigned by Vitally and the externalId if provided when creating the Note

Request Body

Property	Type	Description
accountId	`string`	The ID of the Vitally Account to associate the Note with
organizationId	`string`	The ID of the Vitally Organization account to associate the Note with
note	`string`	The body of the Note, may include HTML (see HTML Fields)
noteDate	`string`	The timestamp of when the Note was created
externalId	`string`	The unique ID of the Note in your system
subject	`string`	The subject or title of the Note
authorId	`string`	The ID of the Vitally User who created the Note
categoryId	`string`	The ID of the Vitally Note Category the Note belongs to
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 Note `DELETE`

US Data Center (default):

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

EU Data Center:

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

Request Params

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

List A Note Categories `GET`

US Data Center (default):

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

EU Data Center:

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

Paginated list of Note Categories.

Note Categories are managed in the Vitally UI. The ID of the Note Category is required for associating a Note with a Note 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/noteCategories?limit=10&from=cursor

Example Response

{
  "results": [
    {
      "id": "xxxx-xxxxx-xxxxxxxx-xxxxxxxx",
      "name": "Call",
      "createdAt": "2020-12-11T20:16:27.370Z",
      "updatedAt": "2020-12-11T20:16:27.370Z"
    },
    {
      "id": "xxxx-xxxxx-xxxxxxxx-xxxxxxxx",
      "name": "Meeting",
      "createdAt": "2020-12-11T20:16:27.370Z",
      "updatedAt": "2020-12-11T20:16:27.370Z"
    }
  ],
  "next": "c29tZWJhc2U2NA=="
}

REST API: Conversations

REST API: Projects

REST API: Tasks

REST API: NPS Responses

REST API: Project Templates

The Note object

The Note Category object

Note custom traits

List Notes GET

List Notes For An Account GET

Query Params (see Pagination)

List Notes For An Organization GET

Query Params (see Pagination)

Create A Note POST

Request Body

Get A Note GET

Request Params

Update A Note PUT

Request Params

Request Body

Delete A Note DELETE

Request Params

List A Note Categories GET

Query Params

List Notes `GET`

List Notes For An Account `GET`

List Notes For An Organization `GET`

Create A Note `POST`

Get A Note `GET`

Update A Note `PUT`

Delete A Note `DELETE`

List A Note Categories `GET`