NPS® Recipients

Every NPS survey is delivered to one or multiple recipients. For most businesses that use Zendesk Support, the recipients are customers. Agents and admins will never receive surveys. If the recipient responds to the survey, they’ll then become a user in your instance of Zendesk Support. If they’re already a user in your Zendesk Support instance, their NPS response will be associated with their user ID. If they’re not an existing user in your Zendesk Support instance, a unique user ID will be created on their behalf to capture their response. Visit the Incremental Export documentation for information on how to export all recipients across surveys.

JSON Format

Recipients are represented as JSON objects with the following keys:

Name Type Read-Only Mandatory Comment
id integer yes no Automatically assigned when the recipient is created
user_id integer yes no The recipient user
email string no yes The email of the recipient
name string no yes The name of the recipient
locale string no no The recipient's locale. Returns the user's locale if present.
created_at date yes no When this recipient was created
updated_at date yes no When the recipient was last updated (i.e., by responding to the survey)
delivered_at date yes no When the survey was delivered to the recipient
Example
{
  "id":           1,
  "user_id":      154506367,
  "email":        "recipient@email.com",
  "name":         "Recipient Name",
  "locale":       "en-US",
  "created_at":   "2013-08-29T00:00:00-07:00",
  "updated_at":   "2013-08-29T00:00:30-07:00",
  "delivered_at": "2013-08-29T00:00:30-07:00"
}

List Recipients

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

Lists all responses for a given survey.

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

{
  "recipients": [
    {
      "id": 1,
      "user_id": null,
      "email": "one@example.org",
      "name": "Recipient One",
      "locale": "en-US",
      "created_at": "2015-07-01T18:00:00Z",
      "updated_at": "2015-07-01T18:00:00Z",
      "delivered_at": "2015-07-01T18:00:00Z"
    },
    ...
  ]
}

Show Recipient

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

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

{
  "recipient": {
    "id": 1,
    "user_id": null,
    "email": "one@example.org",
    "name": "Recipient One",
    "locale": "en-US",
    "created_at": "2015-07-01T18:00:00Z",
    "updated_at": "2015-07-01T18:00:00Z",
    "delivered_at": "2015-07-01T18:00:00Z"
  }
}

Create Recipient

POST /api/v2/nps/surveys/{survey_id}/recipients.json

Creates a new recipient for a survey.

Allowed for
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/nps/surveys/{survey_id}/recipients.json \
  -d '{ "recipient": { "email": "one@example.org", "name": "Recipient One" } }'
  -H "Content-Type: application/json" -v -u {email_address}:{password} -X POST
Example Response
Status: 201 Created

{
  "recipient": {
    "id": 1,
    "user_id": null,
    "email": "one@example.org",
    "name": "Recipient One",
    "locale": "en-US",
    "created_at": "2015-07-01T18:00:00Z",
    "updated_at": "2015-07-01T18:00:00Z",
    "delivered_at": "2015-07-01T18:00:00Z"
  }
}

Update Recipient

PUT /api/v2/nps/surveys/{survey_id}/recipients/{id}.json

Allowed for
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/nps/surveys/{survey_id}/recipients/{id}.json \
  -d '{ "recipient": { "email": "one@example.org", "name": "Recipient One" } }'
  -H "Content-Type: application/json" -v -u {email_address}:{password} -X PUT
Example Response
Status: 200 OK

{
  "recipient": {
    "id": 1,
    "user_id": null,
    "email": "one@example.org",
    "name": "Recipient One",
    "locale": "en-US",
    "created_at": "2015-07-01T18:00:00Z",
    "updated_at": "2015-07-01T18:00:00Z",
    "delivered_at": "2015-07-01T18:00:00Z"
  }
}

Search Recipients

GET /api/v2/nps/surveys/{survey_id}/recipients/search.json?email={email}

Searches recipients by email address.

Allowed for
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/nps/surveys/{survey_id}/recipients/search.json?email={email} \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "recipients": [
    {
      "id": 1,
      "user_id": null,
      "email": "one@example.org",
      "name": "Recipient One",
      "locale": "en-US",
      "created_at": "2015-07-01T18:00:00Z",
      "updated_at": "2015-07-01T18:00:00Z",
      "delivered_at": "2015-07-01T18:00:00Z"
    },
    ...
  ]
}