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 with the following properties:

Name Type Read-only Mandatory Description
comments_question string false false The question to request feedback. Supports dynamic content.
created_at string true false When the survey was created.
delivery_method string false false The delivery method of the survey. Default: "email". Allowed values are "email" or "web_widget".
email_subject string false false The subject text of the email. Default: "How likely are you to recommend [Company]?"
from_email_id integer false false The chosen sender email ID. Default: ID of the default support address of the account.
highlight_color string false false The color used to highlight certain elements in the survey email and the survey page.
id integer true false Automatically assigned when survey created.
intro_text string false false The introductory text of the email. Default: (Empty String).
name string false false The name of the survey for your internal use.
relationship_id integer false false The ID of relationship value used for the survey question.
status string true false Status of the survey. Allowed values are "closed", "draft" or "open".
subject string false false The subject of the survey. For example, your company name.
updated_at string true false When the survey was last 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
{
  "comments_question": "Will you share why?",
  "created_at": "2013-08-29T00:00:00-07:00",
  "delivery_method": "email",
  "email_subject": "How likely are you to recommend [Company]?",
  "from_email_id": 10001,
  "highlight_color": "#77a500",
  "id": 1,
  "intro_text": "Hi Richard, how are you today?",
  "name": "After Purchase Survey",
  "relationship_id": 4,
  "status": "open",
  "subject": "Zendesk Support",
  "updated_at": "2013-08-29T00:00:00-07:00"
}

List Surveys

  • GET /api/v2/nps/surveys

List existing 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": [
    {
      "comments_question": "Will you let us know why?",
      "created_at": "2020-06-01T00:00:00-07:00",
      "delivery_method": "email",
      "email_subject": "How likely are you to recommend us?",
      "from_email_id": 10001,
      "highlight_color": "#77a500",
      "id": 1,
      "intro_text": "Hi, this is a follow-up to your recent purchase.",
      "name": "After Purchase Survey",
      "relationship_id": 4,
      "status": "open",
      "subject": "Zendesk Support",
      "updated_at": "2020-06-01T00:00:00-07:00"
    }
  ]
}

Show Survey

  • GET /api/v2/nps/surveys/{survey_id}

Shows 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}.json \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

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

Update Survey

  • PUT /api/v2/nps/surveys/{survey_id}

Updates an existing survey.

Allowed for
  • Admins
Parameters
Name Type In Required Description
survey_id integer Path true ID of survey.
Example Body
{
  "survey": {
    "comments_question": "Will you let us know why?",
    "email_subject": "How likely are you to recommend [Company]?",
    "from_email_id": 10001,
    "highlight_color": "#77a500",
    "intro_text": "Hi Richard, how are you today?",
    "name": "After Purchase Survey",
    "relationship_id": 4,
    "subject": "Zendesk Support"
  }
}
Using curl
curl \
  --data \
    '{"survey": { \
      "comments_question": "Will you let us know why?", \
      "created_at": "2020-06-01T00:00:00-07:00", \
      "delivery_method": "email", \
      "email_subject": "How likely are you to recommend us?", \
      "from_email_id": 10001, \
      "highlight_color": "#77a500", \
      "id": 1, \
      "intro_text": "Hi, this is a follow-up to your recent purchase.", \
      "name": "After Purchase Survey", \
      "relationship_id": 4, \
      "status": "open", \
      "subject": "Zendesk Support", \
      "updated_at": "2020-06-01T00:00:00-07:00" \
    }}' \
  --header "Content-Type: application/json" \
  --request PUT \
  -v -u {email_address}:{password} \
    https://{subdomain}.zendesk.com/api/v2/nps/surveys/{survey_id}.json
Example Response
Status 200 OK

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

Close Survey

  • POST /api/v2/nps/surveys/{survey_id}/close

Closes an existing survey.

Allowed for
  • Admins
Parameters
Name Type In Required Description
survey_id integer Path true ID of survey.
Using curl
curl \
  --data '' \
  --request POST \
  -v -u {email_address}:{password} \
    https://{subdomain}.zendesk.com/api/v2/nps/surveys/{survey_id}/close
Example Response
Status 200 OK

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

Preview Survey

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

Previews a survey in a specific locale.

Allowed for
  • Admins
Parameters
Name Type In Required Description
locale string Query true Rendered locale for preview.
survey_id integer Path true ID of survey.
Using curl
curl https://{subdomain}.zendesk.com/api/v2/nps/surveys/{survey_id}/preview.json?locale={locale} \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

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