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 have the following keys:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned on creation
url string yes no The API url of this identity
user_id integer yes yes The id of the user
type string yes yes One of "email", "twitter", "facebook", "google", or "phone_number"
value string yes yes The identifier for this identity, such as an email address
verified boolean no no If the identity has been verified
primary boolean no* no If the identity is the primary identity. *Writable only when creating, not when updating. Use the Make Identify Primary endpoint instead
created_at date yes no The time the identity was created
updated_at date yes no The time the identity was updated
undeliverable_count integer yes no The number of times a soft-bounce response was received at that address. Maximum is 10, after which the deliverable_state is set to "undeliverable"
deliverable_state string yes no Either "deliverable or "undeliverable".
Example
{
  "id":              35436,
  "url":              "https://company.zendesk.com/api/v2/users/135/identities/35436.json",
  "user_id":         135,
  "type":            "email",
  "value":           "someone@example.com",
  "verified":        true,
  "primary":         true,
  "updated_at":      "2011-07-20T22:55:29Z",
  "created_at":      "2011-07-20T22:55:29Z",
  "deliverable_state": "deliverable"
}

List Identities

GET /api/v2/users/{user_id}/identities.json

Returns all user identities for a given user id.

Allowed For
  • Agents
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": [
    {
      "id":              35436,
      "user_id":         135,
      "type":            "email",
      "value":           "someone@example.com",
      "verified":        true,
      "primary":         true,
      "updated_at":      "2011-07-20T22:55:29Z",
      "created_at":      "2011-07-20T22:55:29Z"
    },
    {
      "id":              77136,
      "user_id":         135,
      "type":            "twitter",
      "value":           "didgeridooboy",
      "verified":        true,
      "primary":         false,
      "updated_at":      "2012-02-12T14:25:21Z",
      "created_at":      "2012-02-12T14:25:21Z"
    },
    {
      "id":              88136,
      "user_id":         135,
      "type":            "phone_number",
      "value":           "+1 555-123-4567",
      "verified":        true,
      "primary":         true,
      "updated_at":      "2012-02-12T14:25:21Z",
      "created_at":      "2012-02-12T14:25:21Z"
    }
  ]
}

Show Identity

GET /api/v2/users/{user_id}/identities/{id}.json

Shows the identity with the given id.

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/identities/{id}.json \
  -v -u {email_address}:{password}
Example Response:
Status: 200 OK

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

Create Identity

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

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

Adds a new 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.

Identities that can be added:

  • email - e.g., { "type" : "email", "value" : "someone@example.com" }
  • twitter - e.g., { "type" : "twitter", "value" : "screen_name" }
  • facebook - e.g., { "type" : "facebook", "value" : "855769377321" }
  • google - e.g., { "type" : "google", "value" : "example@gmail.com" }

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

Allowed For
  • Agents
  • Verified end users
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": "foo@bar.com"}}' -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": "foo@bar.com"}}' -v -u {email_address}/token:{api_token}
Example Response
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/users/135/identities/78138.json

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

Update Identity

PUT /api/v2/users/{user_id}/identities/{id}.json

This endpoint allows you to:

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

Note: You can't change an identity's primary attribute with this endpoint. Use the Make Identity Primary endpoint instead.

Allowed For
  • Agents
Using curl

To update verified:

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

To update value:

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

{
  "identity": {
    {
      "id":              35436,
      "user_id":         135,
      "type":            "email",
      "value":           "someone@example.com",
      "verified":        true,
      "primary":         true,
      "updated_at":      "2011-07-20T22:55:29Z",
      "created_at":      "2011-07-20T22:55:29Z",
      "deliverable_state": "deliverable"
    }
  }
}

Make Identity Primary

PUT /api/v2/users/{user_id}/identities/{id}/make_primary

PUT /api/v2/end_users/{user_id}/identities/{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.

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.

Allowed For
  • Agents
  • Verified end users
Using curl (agents only)
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/identities/{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/{id}/make_primary.json \
  -X PUT -v -u {email_address}:{password} -d '{}' -H "Content-Type: application/json"
Example Response

Same as List Identities above.

Verify Identity

PUT /api/v2/users/{user_id}/identities/{id}/verify

Sets the specified identity as verified.

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/identities/{id}/verify.json \
  -X PUT -v -u {email_address}:{password} -d '{}' -H "Content-Type: application/json"
Example Response

Same as Show Identity above.

Request User Verification

PUT /api/v2/users/{user_id}/identities/{id}/request_verification.json

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

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/identities/{id}/request_verification.json \
  -X PUT -v -u {email_address}:{password} -d '{}' -H "Content-Type: application/json"
Example Response
Status: 200 OK

Delete Identity

DELETE /api/v2/users/{user_id}/identities/{id}.json

Deletes the identity for a given user.

Allowed For
  • Agents
Using curl
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/identities/{id}.json \
  -X DELETE -v -u {email_address}:{password}
Example Response
Status: 204 No Content