Note: This API endpoint is deprecated. Zendesk is removing Net Promoter Score℠ (NPS®) survey functionality on April 30, 2023. For more information, see Announcing the removal of Net Promoter Score (NPS).

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 properties:

Name Type Read-only Mandatory Description
created_at string true false When the recipient was created.
delivered_at string true false When the survey was delivered to the recipient.
email string false true The email of the recipient.
id integer true false Automatically assigned when the recipient is created.
locale string false false The recipient's locale.
name string false true The name of the recipient.
updated_at string true false When recipient was last updated (i.e., by responding to the survey).
user_id integer true false The recipient user ID.

Example

{  "created_at": "2013-08-29T00:00:00-07:00",  "delivered_at": "2013-08-29T00:00:30-07:00",  "email": "[email protected]",  "id": 1,  "locale": "en-US",  "name": "Recipient Name",  "updated_at": "2013-08-29T00:00:30-07:00",  "user_id": 154506367}

List Recipients

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

List recipients for a given survey.

Allowed for

  • Admins

Parameters

Name Type In Required Description
survey_id integer Path true ID of survey.

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/nps/surveys/{survey_id}/recipients.json \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/nps/surveys/1234/recipients"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/nps/surveys/1234/recipients")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/nps/surveys/1234/recipients',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/nps/surveys/1234/recipients"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/nps/surveys/1234/recipients")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "recipients": [    {      "created_at": "2020-07-01T18:00:00Z",      "delivered_at": "2020-07-01T20:00:00Z",      "email": "[email protected]",      "id": 1,      "locale": "en-US",      "name": "Recipient One",      "updated_at": "2020-07-01T18:00:00Z",      "user_id": null    }  ]}

Create Recipient

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

Creates a new recipient for a survey.

Allowed for

  • Admins

Parameters

Name Type In Required Description
survey_id integer Path true ID of survey.

Example body

{  "recipient": {    "email": "[email protected]",    "name": "Recipient One"  }}

Code Samples

curl
curl \  --data '{"recipient": {"email": "[email protected]", "name": "Recipient One"}}' \  --header "Content-Type: application/json" \  --request POST \  -v -u {email_address}:{password}    https://{subdomain}.zendesk.com/api/v2/nps/surveys/{survey_id}/recipients.json
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://support.zendesk.com/api/v2/nps/surveys/1234/recipients"	method := "POST"	payload := strings.NewReader(`{  "recipient": {    "email": "[email protected]",    "name": "Recipient One"  }}`)	req, err := http.NewRequest(method, url, payload)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/nps/surveys/1234/recipients")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"recipient\": {    \"email\": \"[email protected].org\",    \"name\": \"Recipient One\"  }}""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("POST", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var data = JSON.stringify({  "recipient": {    "email": "[email protected]",    "name": "Recipient One"  }});
var config = {  method: 'POST',  url: 'https://support.zendesk.com/api/v2/nps/surveys/1234/recipients',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport json
url = "https://support.zendesk.com/api/v2/nps/surveys/1234/recipients"
payload = json.loads("""{  "recipient": {    "email": "[email protected]",    "name": "Recipient One"  }}""")headers = {	"Content-Type": "application/json",}
response = requests.request(	"POST",	url,	auth=('<username>', '<password>'),	headers=headers,	json=payload)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/nps/surveys/1234/recipients")request = Net::HTTP::Post.new(uri, "Content-Type": "application/json")request.body = %q({  "recipient": {    "email": "[email protected]",    "name": "Recipient One"  }})request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

201 Created
// Status 201 Created
{  "recipient": {    "created_at": "2020-07-01T18:00:00Z",    "delivered_at": "2020-07-01T20:00:00Z",    "email": "[email protected]",    "id": 1,    "locale": "en-US",    "name": "Recipient One",    "updated_at": "2020-07-01T18:00:00Z",    "user_id": null  }}

Search Recipients

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

Searches recipients by email address.

Allowed for

  • Admins

Parameters

Name Type In Required Description
email string Query true Email address.
survey_id integer Path true ID of survey.

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/nps/surveys/{survey_id}/recipients/search.json?email={email} \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/nps/surveys/1234/recipients/search?email=user%40domain.org"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/nps/surveys/1234/recipients/search")		.newBuilder()		.addQueryParameter("email", "[email protected]");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/nps/surveys/1234/recipients/search',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  params: {    'email': 'user%40domain.org',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/nps/surveys/1234/recipients/search?email=user%40domain.org"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/nps/surveys/1234/recipients/search")uri.query = URI.encode_www_form("email": "[email protected]")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "recipients": [    {      "created_at": "2020-07-01T18:00:00Z",      "delivered_at": "2020-07-01T20:00:00Z",      "email": "[email protected]",      "id": 1,      "locale": "en-US",      "name": "Recipient One",      "updated_at": "2020-07-01T18:00:00Z",      "user_id": null    }  ]}

Show Recipient

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

Shows an existing recipient for a survey.

Allowed for

  • Admins

Parameters

Name Type In Required Description
recipient_id integer Path true ID of survey recipient.
survey_id integer Path true ID of survey.

Code Samples

curl
curl https://{subdomain}.zendesk.com/api/v2/nps/surveys/{survey_id}/recipients/{recipient_id}.json \  -v -u {email_address}:{password}
Go
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://support.zendesk.com/api/v2/nps/surveys/1234/recipients/2468"	method := "GET"	req, err := http.NewRequest(method, url, nil)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/nps/surveys/1234/recipients/2468")		.newBuilder();
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://support.zendesk.com/api/v2/nps/surveys/1234/recipients/2468',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requests
url = "https://support.zendesk.com/api/v2/nps/surveys/1234/recipients/2468"headers = {	"Content-Type": "application/json",}
response = requests.request(	"GET",	url,	auth=('<username>', '<password>'),	headers=headers)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/nps/surveys/1234/recipients/2468")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "recipient": {    "created_at": "2020-07-01T18:00:00Z",    "delivered_at": "2020-07-01T20:00:00Z",    "email": "[email protected]",    "id": 1,    "locale": "en-US",    "name": "Recipient One",    "updated_at": "2020-07-01T18:00:00Z",    "user_id": null  }}

Update Recipient

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

Updates an existing recipient for a survey.

Allowed for

  • Admins

Parameters

Name Type In Required Description
recipient_id integer Path true ID of survey recipient.
survey_id integer Path true ID of survey.

Example body

{  "recipient": {    "email": "[email protected]",    "name": "Recipient One"  }}

Code Samples

curl
curl \  --data '{"recipient": {"email": "[email protected]", "name": "Recipient One"}}' \  --header "Content-Type: application/json" \  --request PUT \  -v -u {email_address}:{password} \    https://{subdomain}.zendesk.com/api/v2/nps/surveys/{survey_id}/recipients/{recipient_id}.json
Go
import (	"fmt"	"io"	"net/http"	"strings")
func main() {	url := "https://support.zendesk.com/api/v2/nps/surveys/1234/recipients/2468"	method := "PUT"	payload := strings.NewReader(`{  "recipient": {    "email": "[email protected]",    "name": "Recipient One"  }}`)	req, err := http.NewRequest(method, url, payload)
	if err != nil {		fmt.Println(err)		return	}	req.Header.Add("Content-Type", "application/json")	req.Header.Add("Authorization", "Basic <auth-value>") // Base64 encoded "username:password"
	client := &http.Client {}	res, err := client.Do(req)	if err != nil {		fmt.Println(err)		return	}	defer res.Body.Close()
	body, err := io.ReadAll(res.Body)	if err != nil {		fmt.Println(err)		return	}	fmt.Println(string(body))}
Java
import com.squareup.okhttp.*;OkHttpClient client = new OkHttpClient();HttpUrl.Builder urlBuilder = HttpUrl.parse("https://support.zendesk.com/api/v2/nps/surveys/1234/recipients/2468")		.newBuilder();RequestBody body = RequestBody.create(MediaType.parse("application/json"),		"""{  \"recipient\": {    \"email\": \"[email protected].org\",    \"name\": \"Recipient One\"  }}""");
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("PUT", body)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", Credentials.basic("your-email", "your-password"))		.build();Response response = client.newCall(request).execute();
Nodejs
var axios = require('axios');var data = JSON.stringify({  "recipient": {    "email": "[email protected]",    "name": "Recipient One"  }});
var config = {  method: 'PUT',  url: 'https://support.zendesk.com/api/v2/nps/surveys/1234/recipients/2468',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "username:password"  },  data : data,};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python
import requestsimport json
url = "https://support.zendesk.com/api/v2/nps/surveys/1234/recipients/2468"
payload = json.loads("""{  "recipient": {    "email": "[email protected]",    "name": "Recipient One"  }}""")headers = {	"Content-Type": "application/json",}
response = requests.request(	"PUT",	url,	auth=('<username>', '<password>'),	headers=headers,	json=payload)
print(response.text)
Ruby
require "net/http"uri = URI("https://support.zendesk.com/api/v2/nps/surveys/1234/recipients/2468")request = Net::HTTP::Put.new(uri, "Content-Type": "application/json")request.body = %q({  "recipient": {    "email": "[email protected]",    "name": "Recipient One"  }})request.basic_auth "username", "password"response = Net::HTTP.start uri.hostname, uri.port, use_ssl: true do |http|	http.request(request)end

Example response(s)

200 OK
// Status 200 OK
{  "recipient": {    "created_at": "2020-07-01T18:00:00Z",    "delivered_at": "2020-07-01T20:00:00Z",    "email": "[email protected]",    "id": 1,    "locale": "en-US",    "name": "Recipient One",    "updated_at": "2020-07-01T18:00:00Z",    "user_id": null  }}