REST API: NPS Responses

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 NPS Response object

Property	Description	Editable
id	Vitally's unique ID for the NPS Response	No
createdAt	Datetime the NPS Response was created	No
updatedAt	Datetime the NPS Response was last updated	No
externalId	Your unique ID for the NPS Response	Only on create
userId	Required The ID of the Vitally User the NPS Response is from	Yes
score	Required The numerical score (0-10)	Yes
feedback	The text feedback submitted with the response	Yes
respondedAt	The date-time the user submitted the response	Yes

List NPS Responses GET

US Data Center (default):

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

EU Data Center:

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

Paginated list of NPS Responses, by default ordered by updatedAt.

Query Params (see Pagination)

Example Request

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

Example Response

{
  "results": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "externalId": "nps-response-1",
      "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "score": 9,
      "feedback": "I think the product is great!",
      "respondedAt": "2020-12-29T20:16:27.370Z"
    }
  ],
  "next": "c29tZWJhc2U2NA=="
}

List NPS Responses For An Account GET

US Data Center (default):

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

EU Data Center:

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

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

Request Params

Property	Type	Description
accountId	string	The Account ID assigned by Vitally

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/accounts/:accountId/npsResponses?limit=10&from=cursor

Example Response

{
  "results": [
    {
      "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "externalId": "nps-response-1",
      "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "score": 9,
      "feedback": "I think the product is great!",
      "respondedAt": "2020-12-29T20:16:27.370Z"
    }
  ],
  "next": "c29tZWJhc2U2NA=="
}

Create An NPS Response POST

US Data Center (default):

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

EU Data Center:

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

NPS Response's are unique on externalId. So creating and updating are both possible via the POST endpoint.

Request Body

Property	Type	Description
userId	string	Required The Vitally assigned ID of the Vitally User to associate the NPS Response with. This is NOT the external ID you assign for the user, but the ID that Vitally assigns.
respondedAt	string	Required The timestamp of when the NPS Response was submitted
score	number	Required The score of the NPS Response
externalId	string	The unique ID of the NPS Response in your system
feedback	string	The text feedback the User submitted

Example Request

POST https://{subdomain}.rest.vitally.io/resources/npsResponses
{
  "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "externalId": "nps-response-1",
  "score": 9,
  "feedback": "I think the product is great!",
  "respondedAt": "2020-12-29T20:16:27.370Z",
}

Example Response

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "externalId": "nps-response-1",
  "userId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "score": 9,
  "feedback": "I think the product is great!",
  "respondedAt": "2020-12-29T20:16:27.370Z"
}

Get An NPS Response GET

US Data Center (default):

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

EU Data Center:

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

Request Params

Property	Type	Description
id	string	The NPS Response ID assigned by Vitally

Update An NPS Response PUT

US Data Center (default):

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

EU Data Center:

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

Request Params

Property	Type	Description
id	string	Accepts both the NPS Repsonse ID assigned by Vitally and the externalId if provided when creating the NPS Response

Request Body

Property	Type	Description
userId	string	Required The Vitally assigned ID of the Vitally User to associate the NPS Response with
respondedAt	string	Required The timestamp of when the NPS Response was submitted
score	number	Required The score of the NPS Response
feedback	string	The text feedback the User submitted

Delete An NPS Response DELETE

US Data Center (default):

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

EU Data Center:

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

Request Params

Property	Type	Description
id	string	The NPS Response ID assigned by Vitally