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