NPS® Invitations
Note: This API endpoint is deprecated. Zendesk is removing Net Promoter Score℠ (NPS®) survey functionality on April 30, 2023. For more information, see Announcing the removal of Net Promoter Score (NPS).
You can send an invitation to one or multiple recipients to take an NPS survey. You can use an API to set up a continuous delivery of NPS survey invites to your defined recipients. Perhaps you want to offer an NPS survey every time a customer makes a purchase, or perhaps you want to offer a survey 30 days after a customer signs up for your service. How you want to serve up an NPS survey to your customers is up to you.
JSON format
Invitations are represented as JSON objects with the following properties:
Name | Type | Read-only | Mandatory | Description |
---|---|---|---|---|
created_at | string | true | false | When the invitation was created. |
delivered_at | string | true | false | When the invitation was delivered. |
id | integer | true | false | Automatically assigned when a survey invitation is created. |
recipients_count | integer | true | false | The number of invitation recipients. |
status | string | true | false | Status of the invitation. Allowed values are "delivered", "failed", "preparing", "scheduled", or "zero_recipients". |
survey_id | integer | true | false | Survey ID associated with the survey invitation - only present for create invitation responses. |
updated_at | string | true | false | When the invitation was last updated. |
Example
{
"created_at": "2014-01-07T10:22:00Z",
"delivered_at": "2014-01-07T17:22:00Z",
"id": 1,
"recipients_count": 25,
"status": "scheduled",
"updated_at": "2014-01-07T15:02:00Z"
}
List Invitations
GET /api/v2/nps/surveys/{survey_id}/invitations
List all invitations for an existing survey.
Allowed for
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
survey_id | integer | Path | true | ID of survey. |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/nps/surveys/{survey_id}/invitations.json \
-v -u {email_address}:{password}
Example response(s)
200 OK
Status 200 OK
{
"invitations": [
{
"created_at": "2020-01-07T10:22:00Z",
"delivered_at": "2020-01-07T17:22:00Z",
"id": 1,
"recipients_count": 20,
"status": "delivered",
"updated_at": "2020-01-07T15:02:00Z"
},
{
"created_at": "2020-01-08T05:12:00Z",
"delivered_at": "2020-01-08T10:32:00Z",
"id": 2,
"recipients_count": 10,
"status": "delivered",
"updated_at": "2020-01-08T08:10:00Z"
}
]
}
Create Invitation
POST /api/v2/nps/surveys/{survey_id}/invitations
Sends invitations for a survey to a list of recipients.
The POST request takes one parameter, an invitation object that lists the survery recipients when the invitation is created. The array of recipient information includes the name, email, and language (optional). The maximum number of recipients you can be sent is 10000.
Note: 422 errors are possible if you make subsequent API requests to add recipients while the first invitations are still being sent out. See Creating an NPS Survey in the Support Help Center.
Allowed for
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
survey_id | integer | Path | true | ID of survey. |
Example body
{
"invitation": {
"recipients": [
{
"email": "[email protected]",
"language": "en-US",
"name": "Peter"
},
{
"email": "[email protected]",
"language": "en-US",
"name": "David"
}
]
}
}
Using curl
curl \
--data \
'{"invitation": { \
{"recipients": [ \
{"email": "[email protected]", "language": "en-US", "name": "Jane Doe"}, \
{"email": "[email protected]", "language": "en-US", "name": "Mike Smith"} \
]}
}}' \
--header "Content-Type: application/json" \
--request POST \
https://{subdomain}.zendesk.com/api/v2/nps/surveys/{survey_id}/invitations.json
Example response(s)
201 Created
Status 201 Created
{
"invitation": {
"created_at": "2020-01-07T10:22:00Z",
"id": 1,
"survey_id": 1,
"updated_at": "2020-01-07T10:22:00Z"
}
}
Show Invitation
GET /api/v2/nps/surveys/{survey_id}/invitations/{invitation_id}
Shows an existing invitation for a survey.
Allowed for
- Admins
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
invitation_id | integer | Path | true | ID of invitation. |
survey_id | integer | Path | true | ID of survey. |
Using curl
curl https://{subdomain}.zendesk.com/api/v2/nps/surveys/{survey_id}/invitations/{invitation_id}.json \
-v -u {email_address}:{password}
Example response(s)
200 OK
Status 200 OK
{
"invitation": {
"created_at": "2020-01-07T10:22:00Z",
"delivered_at": "2020-01-07T17:22:00Z",
"id": 1,
"recipients_count": 8,
"status": "scheduled",
"updated_at": "2020-01-07T15:02:00Z"
}
}