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