DocumentationAPI Reference

User Identities

A user identity is something that can be used to identify an individual. Most likely, it's an email address, an X (formerly Twitter) handle, or a phone number. Zendesk Support supports a series of different such identities.

This API does not support OAuth tokens scoped for "users:write" or "users:read". See Scopes.

JSON format

User Identities are represented as JSON objects with the following properties:

NameTypeRead-onlyMandatoryDescription
created_atstringtruefalseThe time the identity was created
deliverable_statestringtruefalseEmail identity type only. Indicates if Zendesk sends notifications to the email address. See Deliverable state
idintegertruefalseAutomatically assigned on creation
primarybooleanfalsefalseIf the identity is the primary identity. *Writable only when creating, not when updating. Use the Make Identity Primary endpoint instead
typestringtruetrueThe type of this identity. Allowed values are "email", "twitter", "facebook", "google", "phone_number", "agent_forwarding", "any_channel", "foreign", "sdk", or "messaging".
undeliverable_countintegertruefalseThe number of times a soft-bounce response was received at that address
updated_atstringtruefalseThe time the identity was updated
urlstringtruefalseThe API url of this identity
user_idintegertruetrueThe id of the user
valuestringtruetrueThe identifier for this identity, such as an email address
verification_methodstringfalsefalseIndicates the state of user identity verification. See Verification method. Allowed values are "none", "low", "sso", "embed", or "full".
verifiedbooleanfalsefalse(Deprecated). If the identity has been verified. Deprecated. Use verification_method as a more accurate representation of a user's state of verification.
verified_atstringtruefalseThe last time a full verification flow was completed for the identity

If the identity is of type "phone_number", the phone number must be a direct line, not a shared phone number. See Phone Number in the Users API.

Deliverable state

When a user has multiple email addresses, Zendesk will choose the best one to deliver email notifications. The deliverable_state property helps to determine that identity. If the value is "deliverable", Zendesk will likely use that identity over other email addresses; in the same way, Zendesk will not choose an email address that will likely fail to receive an email.

ValueDescription
deliverableEmail address marked as deliverable
undeliverableEmail address marked as undeliverable
ticket_sharing_partnerEmail address used by a Ticket Sharing Partner integration between two Zendesk instances. Considered undeliverable to prevent email loops
mailing_listEmail address used for mailing lists with multiple individual recipients. Considered undeliverable to prevent email loops
reserved_exampleEmail address used for documentation and testing only. Includes @example.com, @example.net, @example.org, and @example.edu. Considered undeliverable because it's a reserved example domain
machineEmail address used by other providers to deliver machine-generated emails (like automatic responses, marketing campaigns). Considered undeliverable to prevent email loops
mailer_daemonEmail address reserved for delivery notifications agents. Includes [email protected] and @mailer-daemon.domain.com. Considered undeliverable because it's a machine address
mandatoryEmail address marked as mandatory. Zendesk will prefer this address in some situations when the user switches identities

Verification method

Email verification settles a trusted connection of ownership between a specific Zendesk user and an email identity. The verification property indicates whether or not a full email verification has taken place.

The verification_method property can have any of the following values:

ValueDescription
noneThe user has provided an email address
lowAn individual agent has marked the email as verified
ssoThe identity provider has included the email as a SAML assertion or claim, as part of SSO login flow
embedThe email was provided in a JWT as part of an embedded Web Widget or SDK login flow. See Setting up user authentication
fullZendesk has run an email verification flow first hand

The API only allows the verification_method property to be directly set to the values "none" or "low". For example, the only way to get the value to "full" would be to have the end user complete an email verification flow. An attempt to set "sso", "embed" or "full" verification_method states directly is rejected with a 400 Bad Request error.

Example

{  "created_at": "2011-07-20T22:55:29Z",  "deliverable_state": "deliverable",  "id": 35436,  "primary": true,  "type": "email",  "updated_at": "2011-07-20T22:55:29Z",  "url": "https://company.zendesk.com/api/v2/users/135/identities/35436",  "user_id": 135,  "value": "[email protected]",  "verification_method": "full",  "verified": true,  "verified_at": "2011-07-20T22:55:29Z"}

List End User Identities

  • GET /api/v2/end_users/{user_id}/identities

Returns a list of identities for the given end user.

End users can only list email and phone number identities.

Pagination

  • Cursor pagination (recommended)
  • Offset pagination

See Pagination.

Returns a maximum of 100 records per page for cursor pagination.

Allowed For

  • Verified end users

Parameters

NameTypeInRequiredDescription
type[]stringQueryfalseFilters results by one or more identity types using the format ?type[]={type}&type[]={type}. Allowed values are "email", or "phone_number".
user_idintegerPathtrueThe id of the user

Code Samples

curl 
curl https://{subdomain}.zendesk.com/api/v2/end_users/{user_id}/identities \  -H "Authorization: Bearer {access_token}"
Go 
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/end_users/35436/identities?type[]="	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 "{email_address}/token:{api_token}"
	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://example.zendesk.com/api/v2/end_users/35436/identities")		.newBuilder()		.addQueryParameter("type[]", "");String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs 
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/end_users/35436/identities',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },  params: {    'type[]': '',  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python 
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/end_users/35436/identities?type[]="headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby 
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/end_users/35436/identities")uri.query = URI.encode_www_form("type[]": "")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"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
{  "identities": [    {      "created_at": "2011-07-20T22:55:29Z",      "id": 35436,      "primary": true,      "type": "email",      "updated_at": "2011-07-20T22:55:29Z",      "user_id": 135,      "value": "[email protected]",      "verification_method": "low",      "verified": true    },    {      "created_at": "2012-02-12T14:25:21Z",      "id": 77136,      "primary": false,      "type": "twitter",      "updated_at": "2012-02-12T14:25:21Z",      "user_id": 135,      "value": "didgeridooboy",      "verification_method": "low",      "verified": true    },    {      "created_at": "2012-02-12T14:25:21Z",      "id": 88136,      "primary": true,      "type": "phone_number",      "updated_at": "2012-02-12T14:25:21Z",      "user_id": 135,      "value": "+1 555-123-4567",      "verification_method": "low",      "verified": true    }  ]}

Show End User Identity

  • GET /api/v2/end_users/{user_id}/identities/{user_identity_id}

Shows the identity with the given id for a given end user.

End users can only view email or phone number identity.

Allowed For

  • Verified end users

Parameters

NameTypeInRequiredDescription
user_idintegerPathtrueThe id of the user
user_identity_idintegerPathtrueThe ID of the user identity

Code Samples

curl 
curl https://{subdomain}.zendesk.com/api/v2/end_users/{user_id}/identities/{user_identity_id} \  -H "Authorization: Bearer {access_token}"
Go 
import (	"fmt"	"io"	"net/http")
func main() {	url := "https://example.zendesk.com/api/v2/end_users/35436/identities/77938"	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 "{email_address}/token:{api_token}"
	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://example.zendesk.com/api/v2/end_users/35436/identities/77938")		.newBuilder();String userCredentials = "your_email_address" + "/token:" + "your_api_token";String basicAuth = "Basic " + java.util.Base64.getEncoder().encodeToString(userCredentials.getBytes());
Request request = new Request.Builder()		.url(urlBuilder.build())		.method("GET", null)		.addHeader("Content-Type", "application/json")		.addHeader("Authorization", basicAuth)		.build();Response response = client.newCall(request).execute();
Nodejs 
var axios = require('axios');
var config = {  method: 'GET',  url: 'https://example.zendesk.com/api/v2/end_users/35436/identities/77938',  headers: {	'Content-Type': 'application/json',	'Authorization': 'Basic <auth-value>', // Base64 encoded "{email_address}/token:{api_token}"  },};
axios(config).then(function (response) {  console.log(JSON.stringify(response.data));}).catch(function (error) {  console.log(error);});
Python 
import requestsfrom requests.auth import HTTPBasicAuth
url = "https://example.zendesk.com/api/v2/end_users/35436/identities/77938"headers = {	"Content-Type": "application/json",}email_address = 'your_email_address'api_token = 'your_api_token'# Use basic authenticationauth = HTTPBasicAuth(f'{email_address}/token', api_token)
response = requests.request(	"GET",	url,	auth=auth,	headers=headers)
print(response.text)
Ruby 
require "net/http"require "base64"uri = URI("https://example.zendesk.com/api/v2/end_users/35436/identities/77938")request = Net::HTTP::Get.new(uri, "Content-Type": "application/json")email = "your_email_address"api_token = "your_api_token"credentials = "#{email}/token:#{api_token}"encoded_credentials = Base64.strict_encode64(credentials)request["Authorization"] = "Basic #{encoded_credentials}"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
{  "identity": {    "created_at": "2012-02-12T14:25:21Z",    "id": 77938,    "primary": false,    "type": "twitter",