User Identities

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

JSON Format

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

Name Type Read-only Mandatory Description
created_at string true false The time the identity was created
deliverable_state string true false Email identity type only. Indicates if Zendesk sends notifications to the email address. See Deliverable state
id integer true false Automatically assigned on creation
primary boolean false false If the identity is the primary identity. *Writable only when creating, not when updating. Use the Make Identity Primary endpoint instead
type string true true The type of this identity. Allowed values are "email", "twitter", "facebook", "google", "phone_number", "agent_forwarding", "any_channel", "foreign", or "sdk".
undeliverable_count integer true false The number of times a soft-bounce response was received at that address
updated_at string true false The time the identity was updated
url string true false The API url of this identity
user_id integer true true The id of the user
value string true true The identifier for this identity, such as an email address
verified boolean false false If the identity has been verified

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

If the identity is an email address, the deliverable_state property indicates whether Zendesk sends email notifications to the address. If the value is "deliverable", Zendesk sends notifications to the address. Zendesk does not send notifications if the value is one of the following:

Value Description
undeliverable Email address marked as undeliverable
mailing_list Email address used for mailing lists with multiple individual recipients. Considered undeliverable to prevent email loops
ticket_sharing_partner Email address used by a Ticket Sharing Partner integration between two Zendesk instances. Considered undeliverable to prevent email loops
reserved_example Email 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
mailer_daemon Email address reserved for delivery notifications agents. Includes [email protected] and @mailer-daemon.domain.com. Considered undeliverable because it's a machine address
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.json",
  "user_id": 135,
  "value": "[email protected]",
  "verified": true
}

List Identities

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

Returns a list of identities for the given user.

Pagination
  • Cursor pagination (recommended)
  • Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

Allowed For
  • Agents
Parameters
Name Type In Required Description
user_id integer Path true The ID of the user
Using curl
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/identities.json \
  -v -u {email_address}:{password}
Example Response
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]",
      "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",
      "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",
      "verified": true
    }
  ]
}

Create Identity

  • POST /api/v2/users/{user_id}/identities
  • POST /api/v2/end_users/{user_id}/identities.json

Adds an identity to a user's profile. An agent can add an identity to any user profile. An end user can only add an identity to their own user profile.

Use the first endpoint if authenticating as an agent. Use the second if authenticating as an end user. End users must authenticate with a token.

Supported identity types:

Type Example
email { "type" : "email", "value" : "[email protected]" }
twitter { "type" : "twitter", "value" : "screen_name" }
facebook { "type" : "facebook", "value" : "855769377321" }
google { "type" : "google", "value" : "[email protected]" }
agent_forwarding { "type" : "agent_forwarding", "value" : "+1 555-123-4567" }
phone_number { "type" : "phone_number", "value" : "+1 555-123-4567" }

To create an identity without sending out a verification email, include a "verified": true property.

Allowed For
  • Agents
  • Verified end users
Parameters
Name Type In Required Description
user_id integer Path true The ID of the user
Using curl

Agents only

curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/identities.json \
  -H "Content-Type: application/json" -X POST \
  -d '{"identity": {"type": "email", "value": "[email protected]"}}' -v -u {email_address}:{password}
Using curl

Verified end users only

curl https://{subdomain}.zendesk.com/api/v2/end_users/{user_id}/identities.json \
  -H "Content-Type: application/json" -X POST \
  -d '{"identity": {"type": "email", "value": "[email protected]"}}' -v -u {email_address}/token:{api_token}
Example Response
Status 201 Created

{
  "identity": {
    "created_at": "2012-02-12T14:25:21Z",
    "id": 77938,
    "primary": false,
    "type": "twitter",
    "updated_at": "2012-02-12T14:25:21Z",
    "user_id": 13531,
    "value": "cabanaboy",
    "verified": false
  }
}

Show Identity

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

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

Allowed For
  • Agents
Parameters
Name Type In Required Description
user_id integer Path true The ID of the user
user_identity_id integer Path true The ID of the user identity
Using curl
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/identities/{user_identity_id}.json \
  -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "identity": {
    "created_at": "2012-02-12T14:25:21Z",
    "id": 77938,
    "primary": false,
    "type": "twitter",
    "updated_at": "2012-02-12T14:25:21Z",
    "user_id": 13531,
    "value": "cabanaboy",
    "verified": false
  }
}

Update Identity

  • PUT /api/v2/users/{user_id}/identities/{user_identity_id}

This endpoint allows you to:

  • Set the specified identity as verified (but you cannot unverify a verified identity)
  • Update the value property of the specified identity

You can't change an identity's primary attribute with this endpoint. You must use the Make Identity Primary endpoint instead.

Allowed For
  • Agents
Parameters
Name Type In Required Description
user_id integer Path true The ID of the user
user_identity_id integer Path true The ID of the user identity
Using curl

To update verified

curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/identities/{user_identity_id}.json \
  -H "Content-Type: application/json" -X PUT \
  -d '{"identity": {"verified": true}}' -v -u {email_address}:{password}
Using curl

To update value

curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/identities/{user_identity_id}.json \
  -H "Content-Type: application/json" -X PUT \
  -d '{"identity": {"value": "[email protected]"}}' -v -u {email_address}:{password}
Example Response
Status 200 OK

{
  "identity": {
    "created_at": "2011-07-20T22:55:29Z",
    "deliverable_state": "deliverable",
    "id": 35436,
    "primary": true,
    "type": "email",
    "updated_at": "2011-07-20T22:55:29Z",
    "user_id": 135,
    "value": "[email protected]",
    "verified": true
  }
}

Delete Identity

  • DELETE /api/v2/users/{user_id}/identities/{user_identity_id}

Deletes the identity for a given user.

Allowed For
  • Agents
Parameters
Name Type In Required Description
user_id integer Path true The ID of the user
user_identity_id integer Path true The ID of the user identity
Using curl
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/identities/{user_identity_id}.json \
  -X DELETE -v -u {email_address}:{password}
Example Response
Status 204 No Content

Make Identity Primary

  • PUT /api/v2/users/{user_id}/identities/{user_identity_id}/make_primary
  • PUT /api/v2/end_users/{user_id}/identities/{user_identity_id}/make_primary

Sets the specified identity as primary. To change other attributes, use the Update Identity endpoint. This is a collection-level operation and the correct behavior for an API client is to subsequently reload the entire collection.

The first endpoint is the preferred option if authenticating as an agent. If authenticating as an end user, you can only use the second endpoint. End users must authenticate with a token.

Allowed For
  • Agents
  • Verified end users
Parameters
Name Type In Required Description
user_id integer Path true The ID of the user
user_identity_id integer Path true The ID of the user identity
Using curl

Agents only

curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/identities/{user_identity_id}/make_primary.json \
  -X PUT -v -u {email_address}:{password} -d '{}' -H "Content-Type: application/json"
Using curl

Verified end users only

curl https://{subdomain}.zendesk.com/api/v2/end_users/{user_id}/identities/{user_identity_id}/make_primary.json \
  -X PUT -v -u {email_address}:{password} -d '{}' -H "Content-Type: application/json"
Example Response
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]",
      "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",
      "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",
      "verified": true
    }
  ]
}

Request User Verification

  • PUT /api/v2/users/{user_id}/identities/{user_identity_id}/request_verification

Sends the user a verification email with a link to verify ownership of the email address.

Allowed For
  • Agents
Parameters
Name Type In Required Description
user_id integer Path true The ID of the user
user_identity_id integer Path true The ID of the user identity
Using curl
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/identities/{user_identity_id}/request_verification.json \
  -X PUT -v -u {email_address}:{password} -d '{}' -H "Content-Type: application/json"
Example Response
Status 200 OK

Verify Identity

  • PUT /api/v2/users/{user_id}/identities/{user_identity_id}/verify

Sets the specified identity as verified.

Allowed For
  • Agents
Parameters
Name Type In Required Description
user_id integer Path true The ID of the user
user_identity_id integer Path true The ID of the user identity
Using curl
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/identities/{user_identity_id}/verify.json \
  -X PUT -v -u {email_address}:{password} -d '{}' -H "Content-Type: application/json"
Example Response
Status 200 OK

{
  "identity": {
    "created_at": "2012-02-12T14:25:21Z",
    "id": 77938,
    "primary": false,
    "type": "twitter",
    "updated_at": "2012-02-12T14:25:21Z",
    "user_id": 13531,
    "value": "cabanaboy",
    "verified": false
  }
}