NPS® Surveys

The Surveys API can be used to list all surveys or retrieve and update an existing survey. You can customize the content and settings of the survey before using the Invitations API to automate the delivery of your survey to recipients.

JSON Format

Surveys are represented as JSON objects which have the following keys:

Name Type Read-Only Mandatory Comment
id integer yes no Automatically assigned when the survey is created
name string no no The name of the survey for your internal use.
subject string no no The subject of the survey, e.g. your company name.
email_subject string no no The subject text of the email. Default: How likely are you to recommend [Company]?
from_email_id integer no no The chosen sender email ID. Default: ID of the default support address of the account.
intro_text string no no The introductory text of the email. Default: (Empty String)
highlight_color string no no The color used to highlight certain elements in the survey email and the survey page
relationship_id integer no no The ID of relationship value used for the survey question.
comments_question string no no The question to request feedback. Supports dynamic content.
delivery_method string no no The delivery method of the survey: email or web_widget. Default: email
status string yes no The status of the survey: draft, open or closed
created_at date yes no When the survey was created
updated_at date yes no When the survey was updated

Valid relationship ID values are:

  • 0: a friend or colleague
  • 1: a friend
  • 2: a friend or family member
  • 3: a colleague
  • 4: someone you know
Example
{
  "id":                1,
  "name":              "After Purchase Survey",
  "email_subject":     "How likely are you to recommend [Company]?",
  "from_email_id":     10001,
  "intro_text":        "Hi Richard, how are you today?",
  "subject":           "Zendesk Support",
  "highlight_color":   "#77a500",
  "relationship_id":   4,
  "comments_question": "Will you share why?",
  "status":            "open",
  "delivery_method":   "email",
  "created_at":        "2013-08-29T00:00:00-07:00",
  "updated_at":        "2013-08-29T00:00:00-07:00"
}

List Surveys

GET /api/v2/nps/surveys

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

{
  "surveys": [
    {
      "id": 1,
      "name": "After Purchase Survey",
      "email_subject": "How likely are you to recommend us?",
      "from_email_id": 10001,
      "intro_text": "Hi, this is a follow-up to your recent purchase.",
      "subject": "Zendesk Support",
      "highlight_color": "#77a500",
      "relationship_id": 4,
      "comments_question": "Will you let us know why?",
      "delivery_method": "email",
      "status": "open",
      "created_at": "2013-08-29T00:00:00-07:00",
      "updated_at": "2013-08-29T00:00:00-07:00"
    }
  ]
}

Show Survey

GET /api/v2/nps/surveys/{id}

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

{
  "survey": {
    "id": 1,
    "name": "After Purchase Survey",
    "email_subject": "How likely are you to recommend us?",
    "from_email_id": 10001,
    "intro_text": "Hi, this is a follow-up to your recent purchase.",
    "subject": "Zendesk Support",
    "highlight_color": "#77a500",
    "relationship_id": 4,
    "comments_question": "Will you let us know why?",
    "delivery_method": "email",
    "status": "open",
    "created_at": "2013-08-29T00:00:00-07:00",
    "updated_at": "2013-08-29T00:00:00-07:00"
  }
}

Update Survey

PUT /api/v2/nps/surveys/1

Updates an existing survey.

Allowed for
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/nps/surveys/{id}.json \
  -H "Content-Type: application/json" \
  -d '{ "survey": { "name": "After Purchase Survey", "subject": "Zendesk Support", \
  "email_subject": "How likely are you to recommend [Company]?", \
  "from_email_id": 10001, \
  "intro_text": "Hi Richard, how are you today?", \
  "highlight_color": "#77a500", "relationship_id": 4, "comments_question": "Will you share why?" } }' \
  -v -u {email_address}:{password} -X PUT
Example response
Status: 200 OK

{
  "survey" : {
    "id": 1,
    "name": "After Purchase Survey",
    "email_subject": "How likely are you to recommend us?",
    "from_email_id": 10001,
    "intro_text": "Hi, this is a follow-up to your recent purchase.",
    "subject": "Zendesk Support",
    "highlight_color": "#77a500",
    "relationship_id": 4,
    "comments_question": "Will you let us know why?"
    "delivery_method": "email",
    "status": "open",
    "created_at": "2013-08-29T00:00:00-07:00",
    "updated_at": "2013-08-29T00:00:00-07:00"
  }
}

Preview Survey

GET /api/v2/nps/surveys/{id}/preview?locale={locale}

Previews a survey in a specific locale.

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

{
  "survey_preview": {
    "id": 1,
    "question": "How likely are you to recommend Zendesk Support to someone you know?",
    "comments_question": "Will you let us know why?",
    "highlight_color": "#77a500",
    "logo_url": "http://example.com/logo.jpg",
    "likely_label": "Extremely likely",
    "not_likely_label": "Not at all likely",
    "feedback_placeholder": "Write your comment here...",
    "you_rated": "You rated us a %{rating}",
    "thank_you": "Thank you for your feedback.",
    "status": "open"
  }
}

Close Survey

POST /api/v2/nps/surveys/{id}/close

Allowed for
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/nps/surveys/{id}/close \
  -v -u {email_address}:{password} -d '' -X POST
Example response
Status: 200 OK

{
  "survey": {
    "id": 1,
    "name": "After Purchase Survey",
    "email_subject": "How likely are you to recommend us?",
    "from_email_id": 10001,
    "intro_text": "Hi, this is a follow-up to your recent purchase.",
    "subject": "Zendesk Support",
    "highlight_color": "#77a500",
    "relationship_id": 4,
    "comments_question": "Will you let us know why?",
    "delivery_method": "email",
    "status": "closed",
    "created_at": "2013-08-29T00:00:00-07:00",
    "updated_at": "2013-08-29T00:00:00-07:00"
  }
}