REST API: Notes

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

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

Request Params

id

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