NPS® Invitations

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 which have the following keys:

Name Type Read-Only Comment
id integer yes Automatically assigned upon creation
status string yes Status of the invitation: ['scheduled', 'preparing', 'delivered', 'failed', 'zero_recipients']
recipients_count integer yes The number of invitation recipients
created_at date yes When the invitation was created
updated_at date yes When the invitation was last updated
delivered_at date yes When the invitation was delivered
Example
{
  "id":               1,
  "status":           "scheduled",
  "recipients_count": 25,
  "created_at":       "2014-01-07T10:22:00Z",
  "updated_at":       "2014-01-07T15:02:00Z",
  "delivered_at":     "2014-01-07T17:22:00Z"
}

List Invitations

GET /api/v2/nps/surveys/{survey_id}/invitations.json

Lists all invitations.

Allowed for
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/nps/surveys/1/invitations.json \
  -v -u {email_address}:{password}
Example response
Status: 200 OK

{
  "invitations": [
    {
      "id": 1,
      "status": "delivered",
      "recipients_count": 20,
      "created_at": "2014-01-07T10:22:00Z",
      "updated_at": "2014-01-07T15:02:00Z",
      "delivered_at": "2014-01-07T17:22:00Z",
    },
    {
      "id": 2,
      "status": "delivered",
      "recipients_count": 10,
      "created_at": "2014-01-08T05:12:00Z",
      "updated_at": "2014-01-08T08:10:00Z",
      "delivered_at": "2014-01-08T10:32:00Z",
    }
  ],
  ...
}

Show Invitation

GET /api/v2/nps/surveys/{survey_id}/invitations/{id}.json

Allowed for
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/nps/surveys/1/invitations/{id}.json \
  -v -u {email_address}:{password}
Example response
Status: 200 OK

{
  "invitation": {
    "id": 1,
    "status": "scheduled",
    "recipients_count": 8,
    "created_at": "2014-01-07T10:22:00Z",
    "updated_at": "2014-01-07T15:02:00Z",
    "delivered_at": "2014-01-07T17:22:00Z",
  }
}

Create Invitation

POST /api/v2/nps/surveys/{id}/invitations.json

Sends invitations to an NPS survey to a list of recipients.

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
Using curl
curl https://{subdomain}.zendesk.com/api/v2/nps/surveys/{survey_id}/invitations.json \
  -d '{"invitation": {"recipients": [{"name": "Jane Doe", "email": "[email protected]", "language": "en-US"}]}}' \
  -H "Content-Type: application/json" -v -u {email_address}:{password} -X POST
Example response
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/invitations/{invitation_id}.json

{
  "invitation": {
    "id" : 1,
    "survey_id": 1,
    "created_at": "2015-04-17T20:01:12.453Z",
    "updated_at": "2015-04-17T20:01:12.453Z"
  }
}
Request parameters

The POST request takes one parameter, an invitation object that lists the survery recipients when the invitation is created.

Name Description
recipients An array of recipient information, including name, email, and language (optional). The maximum number of recipients is 10000.
Example request
{
  "invitation": {
    "recipients": [
      {"name": "Jane Doe", "email": "[email protected]", "language": "en-US"}
    ]
  }
}