Support API

Users

Zendesk Support has three types of users: end-users (your customers), agents, and administrators.

End-users

End-users request support through tickets. End-users have access to Help Center where they can view knowledge base articles and community content, access their ticket history, and submit new tickets.

Agents

Agents work in Zendesk Support to solve tickets. Agents can be divided into multiple groups and can also belong to multiple groups. Agents don't have access to administrative configuration in Zendesk Support such as business rules or automations, but can configure their own macros and views.

Administrators

Administrators have all the abilities of agents, plus administrative abilities. Accounts on the Enterprise plan can configure custom roles to give agents varying degrees of administrative access.

Listing Requested Tickets and CC'ed Tickets

Use the Tickets API to list:

Listing Help Center Content by a User

Use the Help Center API to list:

JSON Format for Agent or Admin Requests

When an agent or admin makes the request, users are returned with the following attributes:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when the user is created
email string no* no The user's primary email address. *Writeable on create only. On update, a secondary email is added. See Email Address
name string no yes The user's name
active boolean yes no false if the user has been deleted
alias string no no An alias displayed to end users
chat_only boolean yes no Whether or not the user is a chat-only agent
created_at date yes no The time the user was created
custom_role_id integer no no A custom role if the user is an agent on the Enterprise plan
role_type integer yes no The user's role id. 0 for custom agents, 1 for light agent and 2 for chat agent
details string no no Any details you want to store about the user, such as an address
external_id string no no A unique identifier from another system. The API treats the id as case insensitive. Example: ian1 and Ian1 are the same user
last_login_at date yes no The last time the user signed in to Zendesk Support
locale string no no The user's locale. A BCP-47 compliant tag for the locale. If both "locale" and "locale_id" are present on create or update, "locale_id" is ignored and only "locale" is used.
locale_id integer no no The user's language identifier
moderator boolean no no Designates whether the user has forum moderation capabilities
notes string no no Any notes you want to store about the user
only_private_comments boolean no no true if the user can only create private comments
organization_id integer no no The id of the organization the user is associated with
default_group_id integer no* no The id of the user's default group. *Can only be set on create, not on update
phone string no no The user's primary phone number. See Phone Number below
shared_phone_number boolean yes no Whether the phone number is shared or not. See Phone Number below
photo Attachment no no The user's profile picture represented as an Attachment object
restricted_agent boolean no no If the agent has any restrictions; false for admins and unrestricted agents, true for other agents
role string no no The user's role. Possible values are "end-user", "agent", or "admin"
shared boolean yes no If the user is shared from a different Zendesk Support instance. Ticket sharing accounts only
shared_agent boolean yes no If the user is a shared agent from a different Zendesk Support instance. Ticket sharing accounts only
signature string no no The user's signature. Only agents and admins can have signatures
suspended boolean no no If the agent is suspended. Tickets from suspended users are also suspended, and these users cannot sign in to the end user portal
tags array no no The user's tags. Only present if your account has user tagging enabled
ticket_restriction string no no Specifies which tickets the user has access to. Possible values are: "organization", "groups", "assigned", "requested", null
time_zone string no no The user's time zone. See Time Zone
two_factor_auth_enabled boolean yes no If two factor authentication is enabled.
updated_at date yes no The time the user was last updated
url string yes no The user's API url
user_fields object no no Values of custom fields in the user's profile. See User Fields
verified boolean no no The user's primary identity is verified or not. For secondary identities, see User Identities
report_csv boolean yes no Whether or not the user can access the CSV report on the Search tab of the Reporting page in the Support admin interface. See Analyzing Help Center search results in Help Center. Only available on the Guide Professional plan
Email Address

You can specify a user's primary email address when you create the user. However, specifying an email address when you update the user creates a secondary email. It doesn't update the primary email address.

To update a user's primary email address, use the Make Identity Primary endpoint.

Time Zone

A time_zone name consists of a string such as "Eastern Time (US & Canada)". For a list of valid names, see the Time zone list menu on the Localization page in the Support admin interface (Admin > Account > Localization). For example, if the menu lists "(GMT+02:00) Berlin", then use "Berlin" as the time_zone name.

Request body in User API:

{
  "user": {
    "id":   35436,
    "name": "Johnny Agent",
    "time_zone": "Berlin",
    ...
  }
}
User Fields

You can use the user_fields object to set the value of one or more custom fields in the user's profile. Specify field keys as the properties to set. Example:

"user_fields": {
  "membership_level": "silver",
  "membership_expires": "2019-07-23T00:00:00Z"
}

For more information, see User Fields and Adding custom fields to users.

Phone Number

The phone number should comply with the E.164 international telephone numbering plan. Example +1 555-123-4567. E164 numbers are international numbers with a country dial prefix, usually an area code and a subscriber number. A valid E.164 phone number must include a country calling code.

A phone number can be one of the following types:

  • A direct line linked to a single user, which is indicated by a shared_phone_number attribute of false. A direct line can be used as a user identity
  • A shared number linked to multiple users, indicated by a shared_phone_number attribute of true. A shared number can not be used as a user identity

See Understanding how phone numbers are linked to end-user profiles in the Support Help Center.

Example
 
{
  "id":                    35436,
  "url":                   "https://company.zendesk.com/api/v2/users/35436.json",
  "name":                  "Johnny Agent",
  "external_id":           "sai989sur98w9",
  "alias":                 "Mr. Johnny",
  "created_at":            "2009-07-20T22:55:29Z",
  "updated_at":            "2011-05-05T10:38:52Z",
  "active":                true,
  "verified":              true,
  "shared":                false,
  "shared_agent":          false,
  "locale":                "en-US",
  "locale_id":             1,
  "time_zone":             "Copenhagen",
  "last_login_at":         "2011-05-05T10:38:52Z",
  "email":                 "johnny@example.com",
  "phone":                 "+1 555-123-4567",
  "signature":             "Have a nice day, Johnny",
  "details":               "",
  "notes":                 "Johnny is a nice guy!",
  "organization_id":       57542,
  "role":                  "agent",
  "role_type":             0,
  "custom_role_id":        9373643,
  "moderator":             true,
  "ticket_restriction":    "assigned",
  "only_private_comments": false,
  "tags":                  ["enterprise", "other_tag"],
  "restricted_agent":      true,
  "suspended":             true,
  "photo": {
    "id":           928374,
    "name":         "my_funny_profile_pic.png",
    "content_url":  "https://company.zendesk.com/photos/my_funny_profile_pic.png",
    "content_type": "image/png",
    "size":         166144,
    "thumbnails": [
      {
        "id":           928375,
        "name":         "my_funny_profile_pic_thumb.png",
        "content_url":  "https://company.zendesk.com/photos/my_funny_profile_pic_thumb.png",
        "content_type": "image/png",
        "size":         58298
      }
    ]
  },
  "user_fields": {
    "user_decimal": 5.1,
    "user_dropdown": "option_1",
    "user_date": "2012-07-23T00:00:00Z"
  }
}

JSON Format for End-user Requests

When an end-user makes the request, the user is returned with the following attributes:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned when creating users
email string no no The primary email address of this user
name string no yes The name of the user
created_at date yes no The time the user was created
locale string yes no The locale for this user
locale_id integer no no The language identifier for this user
organization_id integer no no The id of the organization this user is associated with
phone string no no The primary phone number of this user. See Phone Number in the Users API
shared_phone_number boolean yes no Whether the phone number is shared or not. See Phone Number in the Users API
photo Attachment no no The user's profile picture represented as an Attachment object
role string no no The role of the user. Possible values: "end-user", "agent", "admin"
time_zone string no no The time-zone of this user
updated_at date yes no The time of the last update of the user
url string yes no The API url of this user
verified boolean no no The user's primary identity is verified or not. For secondary identities, see User Identities
Example
 
{
  "id":                    35436,
  "url":                   "https://company.zendesk.com/api/v2/end_users/35436.json",
  "name":                  "Johnny End User",
  "created_at":            "2009-07-20T22:55:29Z",
  "updated_at":            "2011-05-05T10:38:52Z",
  "time_zone":             "Copenhagen",
  "email":                 "johnny@example.com",
  "phone":                 "+1 555-123-4567",
  "locale":                "en-US",
  "locale_id":             1,
  "organization_id":       57542,
  "role":                  "end-user",
  "verified":              true,
  "photo": {
    "id":           928374,
    "name":         "my_funny_profile_pic.png",
    "content_url":  "https://company.zendesk.com/photos/my_funny_profile_pic.png",
    "content_type": "image/png",
    "size":         166144,
    "thumbnails": [
      {
        "id":           928375,
        "name":         "my_funny_profile_pic_thumb.png",
        "content_url":  "https://company.zendesk.com/photos/my_funny_profile_pic_thumb.png",
        "content_type": "image/png",
        "size":         58298,
      }
    ]
  }
}

JSON Format for User Related Information

The JSON returned by the user related information endpoint includes the following keys. Note: Depending on the user's permissions, the count results may not match the actual number of tickets returned.

Name Type Read-only Mandatory Comment
assigned_tickets integer yes no Count of assigned tickets
requested_tickets integer yes no Count of requested tickets
ccd_tickets integer yes no Count of collaborated tickets
organization_subscriptions integer yes no Count of organization subscriptions

It also includes the following additional keys about the legacy Web portal:

Name Type Read-only Mandatory Comment
topics integer yes no Count of topics (Web portal only)
topic_comments integer yes no Count of comments on topics (Web portal only)
votes integer yes no Count of votes (Web portal only)
subscriptions integer yes no Count of subscriptions (Web portal only)
entry_subscriptions integer yes no Count of entry subscriptions (Web portal only)
forum_subscriptions integer yes no Count of forum subscriptions (Web portal only)
Example
 
{
  "user_related": {
    "assigned_tickets": 5
    "requested_tickets": 10,
    "ccd_tickets": 3,
    "topics": 2,
    "topic_comments": 7,
    "votes": 3,
    "subscriptions": 4,
    "entry_subscriptions": 1,
    "forum_subscriptions": 2,
    "organization_subscriptions": 1,
  }
}

List Users
  • GET /api/v2/users.json
  • GET /api/v2/groups/{id}/users.json
  • GET /api/v2/organizations/{id}/users.json

Returns a maximum of 100 users per page. See Pagination.

Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users.json \
  -v -u {email_address}:{password}
Filters
  • role={role} for a single role. Possible values are "end-user", "agent", or "admin"
  • role[]={role}&role[]={role} for more than one role
  • permission_set={role_id} for custom roles in the Enterprise plan. You can only filter by one role id per request

Example:

/api/v2/users.json?role[]=admin&role[]=end-user

Note: If filtering by multiple roles in curl, make sure to include the -g flag to prevent curl from interpreting the square brackets as globbing characters. Also enclose the URL in quotes. Example:

curl -g 'https://{subdomain}.zendesk.com/api/v2/users.json?role[]=admin&role[]=end-user' \
  -v -u {email_address}:{password}
Example Response
 
Status: 200

{
  "users": [
    {
      "id": 223443,
      "name": "Johnny Agent",
      ...
    },
    {
      "id": 8678530,
      "name": "James A. Rosen",
      ...
    }
  ]
}

Show User

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

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

{
  "user": {
    "id":   35436,
    "name": "Johnny Agent",
    ...
  }
}

Show Many Users

GET /api/v2/users/show_many.json?ids={ids}

GET /api/v2/users/show_many.json?external_ids={external_ids}

Accepts a comma-separated list of user ids or external ids.

Allowed For:
  • Agents
Using curl:
 
curl https://{subdomain}.zendesk.com/api/v2/users/show_many.json?ids=1,2,3 \
  -v -u {email_address}:{password}
Example Response
 
Status: 200 OK

{
 "users": [
   {
     "id": 345678,
     "name": "Johnny Appleseed",
     ...
   },
   {
     "id": 901234,
     "name": "Rupert Root",
     ...
   }
 ]
}

User related information

GET /api/v2/users/{id}/related.json

See JSON Format for User Related Information.

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

{
  "user_related": {
    "assigned_tickets": 5,
    "requested_tickets": 10,
    "ccd_tickets": 3,
    "topics": 2,
    "topic_comments": 7,
    "votes": 3,
    "subscriptions": 4,
    ...
  }
}

Create User

POST /api/v2/users.json

Allowed For
  • Agents, with restrictions on certain actions
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users.json \
  -d '{"user": {"name": "Roger Wilco", "email": "roge@example.org"}}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}

If you don't specify a role parameter, the new user is assigned the role of end-user.

If you need to create users without sending out a verification email, pass a "verified": true parameter.

Example Response
 
Status: 201 Created
Location: /api/v2/users/{new-user-id}.json

{
  "user": {
    "id":   9873843,
    "name": "Roger Wilco",
    ...
  }
}

Note: If you need to create agents with a specific role, the role parameter only accepts three possible values: "end-user", "agent", and "admin". Therefore, set role to "agent" as well as add a new parameter called "custom_role_id" and give it the actual desired role ID from your Zendesk Support account. This applies to the built-in "light-agent" role of Zendesk Support as well.

Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users.json \
  -d '{"user": {"name": "Roger Wilco", "email": "roge@example.org", "role": "agent, "custom_role_id": 123456}}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}

The user can also be added to a named organization.

curl https://{subdomain}.zendesk.com/api/v2/users/create_or_update.json \
  -d '{"user": {"name": "Roger Wilco", "email": "roge@example.org", "organization": {"name": "VIP Customers"}}}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}

Create User with Multiple Identities

If you have a user with multiple identities, such as email addresses and Twitter accounts, you can also include these values at creation time. This is especially useful when importing users from another system.

curl https://{subdomain}.zendesk.com/api/v2/users.json \
  -d '{"user": {"name": "Roger Wilco", "identities": [{ "type": "email", "value": "test@user.com"}, {"type": "twitter", "value": "tester84" }]}}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}

Create Or Update User

POST /api/v2/users/create_or_update.json

Creates a user if the user does not already exist, or updates an existing user identified by e-mail address or external ID.

Allowed For
  • Agents, with restrictions on certain actions
Using curl

Existing user identified by e-mail address:

curl https://{subdomain}.zendesk.com/api/v2/users/create_or_update.json \
  -d '{"user": {"name": "Roger Wilco", "email": "roge@example.org"}}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}

Existing user identified by external ID:

curl https://{subdomain}.zendesk.com/api/v2/users/create_or_update.json \
  -d '{"user": {"external_id": "account_12345", "name": "Roger Wilco", "email": "new.email@example.org"}}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}

The user can also be added to a named organization.

curl https://{subdomain}.zendesk.com/api/v2/users/create_or_update.json \
  -d '{"user": {"name": "Roger Wilco", "email": "roge@example.org", "organization": {"name": "VIP Customers"}}}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}

If you don't specify a role parameter, the new user is assigned the role of end-user.

If you need to create users without sending out a verification email, pass a "verified": true parameter.

Example Response

If the user was created:

Status: 201 Created
Location: /api/v2/users/{new-user-id}.json

{
  "user": {
    "id":   9873843,
    "name": "Roger Wilco",
    ...
  }
}

If an existing user was updated:

Status: 200 OK
Location: /api/v2/users/{existing-user-id}.json

{
  "user": {
    "id":   9873843,
    "name": "Roger Wilco",
    ...
  }
}

Create Or Update Many Users

POST /api/v2/users/create_or_update_many.json

Accepts an array of up to 100 user objects. For each user, the user is created if it does not already exist, or the existing user is updated.

Allowed For
  • Agents, with restrictions on certain actions
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/create_or_update_many.json \
  -d '{"users": [{"name": "Roger Wilco", "email": "roge@example.org", "role": "agent"}, {"external_id": "account_54321", "name": "Woger Rilco", "email": "woge@example.org", "role": "admin"}]}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}

Each individual user object can identify an existing user by email or by external_id.

Example Response

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job's completion.

Merge Self With Another User

PUT /api/v2/users/me/merge.json

The current user will be merged into the existing user provided in the params. Users can only merge themselves into another user.

Allowed For
  • Verified end users
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/me/merge.json \
  -d '{"user": {"password": "foo1234", "email": "roge@example.org"}}' \
  -H "Content-Type: application/json" -X PUT \
  -v -u {email_address}:{password}
Example Response
 
Status: 200 OK
Location: /api/v2/users/{user-id}.json

{
  "user": {
    "id":   9873843,
    "name": "Roger Wilco",
    ...
  }
}

Merge End Users

PUT /api/v2/users/{id}/merge.json

The end user whose id is provided in the URL will be merged into the existing end user provided in the params. You can merge any two arbitrary end users with the exception of end users created by sharing agreements. Agents and admins cannot be merged.

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

{
  "user": {
    "id":   9873843,
    "name": "Roger Wilco",
    ...
  }
}

Create Many Users

POST /api/v2/users/create_many.json

Accepts an array of up to 100 user objects.

Note: Access to this endpoint is limited. You may not be able to use it to bulk-import users or organizations. If you're unable, a 403 Forbidden error is returned. If you need access and can't use this endpoint, contact us at support@zendesk.com for assistance.

Allowed For
  • Agents, with restrictions on certain actions
Specifying an organization

You can assign a user to an existing organization by setting an organization_id property in the user object. Example:

{
  "users": [
    {
      "name": "Roger Wilco",
      "email": "roge@example.org",
      "organization_id": 567812345
    },
    ...
  ]
}
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/create_many.json \
  -d '{"users": [{"name": "Roger Wilco", "email": "roge@example.org", "role": "agent"}, {"name": "Woger Rilco", "email": "woge@example.org", "role": "admin"}]}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}
Example Response

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job's completion.

Update User

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

Allowed For
  • Agents, with restrictions on certain actions

Agents can only update end users. Administrators can update end users, agents, and administrators.

Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/{id}.json \
  -d '{"user": {"name": "Roger Wilco II"}}' \
  -H "Content-Type: application/json" -X PUT \
  -v -u {email_address}:{password}
Example Response
 
Status: 200 OK

{
  "user": {
    "id":   9873843,
    "name": "Roger Wilco II",
    ...
  }
}

Update Many Users

PUT /api/v2/users/update_many.json

PUT /api/v2/users/update_many.json?ids={ids}

PUT /api/v2/users/update_many.json?external_ids={external_ids}

Bulk or batch updates up to 100 users.

Bulk update

To make the same change to multiple users, use the following endpoint and data format:

https://{subdomain}.zendesk.com/api/v2/users/update_many.json?ids=1,2,3

{
  "user": {
    "organization_id": 1
  }
}
Batch update

To make different changes to multiple users, use the following endpoint and data format:

https://{subdomain}.zendesk.com/api/v2/users/update_many.json

{
  "users": [
    { "id": 10071, "name": "New Name", "organization_id": 1 },
    { "id": 12307, "verified": true }
  ]
}
Allowed For
  • Agents, with restrictions

Agents can only update end users. Administrators can update end users, agents, and administrators.

Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/update_many.json?ids=1,2,3 \
  -d '{"user": {"organization_id": 1}}' \
  -H "Content-Type: application/json" -X PUT \
  -v -u {email_address}:{password}

curl https://{subdomain}.zendesk.com/api/v2/users/update_many.json \
  -d '{"users": [{"id": 10071, "name": "New Name", "organization_id": 1}, {"external_id": "123", "verified": true}]}' \
  -H "Content-Type: application/json" -X PUT \
  -v -u {email_address}:{password}
Example Response

This endpoint returns a job_status JSON object and queues a background job to do the work. Use the Show Job Status endpoint to check for the job's completion.

Bulk Deleting Users

DELETE /api/v2/users/destroy_many.json?ids={ids}

DELETE /api/v2/users/destroy_many.json?external_ids={external_ids}

Accepts a comma-separated list of up to 100 user ids.

Allowed For
  • Admins
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/destroy_many.json?ids=1,2,3 \
  -v -u {email_address}:{password} -X DELETE
Example Response
 
Status: 200 OK

Suspending a User

You can suspend a user by setting its suspended attribute to true.

When a user is suspended, the user is not allowed to sign in to Help Center and all further tickets are suspended.

Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/{id}.json \
  -d '{"user": {"suspended": true}}' \
  -H "Content-Type: application/json" -X PUT \
  -v -u {email_address}:{password}
Example Response
 
{
  "user": {
    "id":        9873843,
    "name":      "Roger Wilco II",
    "suspended": true,
    ...
  }
}

Delete User

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

Allowed For
  • Agents, with restrictions on certain actions
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/{id}.json \
  -v -u {email_address}:{password} \
  -X DELETE
Example Response
 
Status: 200 OK

{
  "user": {
    "id":     9873843,
    "name":   "Roger Wilco II",
    "active": false,
    ...
  }
}

Search Users

GET /api/v2/users/search.json?query={query}

GET /api/v2/users/search.json?external_id={external_id}

Returns an array of users who meet the search criteria.

The query parameter can specify a partial or full value of any user property, including name, email address, notes, or phone. Example: query="jdoe".

For more advanced searches of users, use the Search API.

Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/search.json?query=gil \
  -v -u {email_address}:{password}
Example Response
 
Status: 200

{
  "users": [
    {
      "id":   35436,
      "name": "Robert Jones",
      "notes": "sigil issue"
      ...
    },
    {
      "id":   9873843,
      "name": "Terry Gilliam",
      ...
    },
  ]
}

Autocomplete Users

GET /api/v2/users/autocomplete.json?name={name}

Returns an array of users whose name starts with the value specified in the name paramater. It only returns users with no foreign identities.

Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/autocomplete.json?name=gil \
  -u {email_address}:{password}
Example Response
 
Status: 200

{
  "users": [
    {
      "id":   35436,
      "name": "Giles Winters",
      ...
    },
    {
      "id":   9873843,
      "name": "Gillian Summers",
      ...
    },
  ]
}

Update a User's Profile Image

You can update a user's profile image by uploading a local file or by referring to an image hosted on a different website. The second option may take a few minutes to process.

Using curl

Uploading a local file:

curl https://{subdomain}.zendesk.com/api/v2/users/{id}.json \
  -F "user[photo][uploaded_data]=@/path/to/profile/image.jpg" \
  -v -u {email_address}:{password} -X PUT

Setting a remote image URL:

curl https://{subdomain}.zendesk.com/api/v2/users/{id}.json \
  -d '{"user": {"remote_photo_url": "http://link.to/profile/image.png"}}' \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X PUT

Request User Create

POST /api/v2/users/request_create.json

Sends the owner a reminder email to update their subscription so more agents can be created.

Allowed For
  • Agents
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/request_create.json \
  -d '{"user": {"name": "Roger Wilco", "email": "roge@example.org"}}' \
  -H "Content-Type: application/json" \
  -X POST -v -u {email_address}:{password}
Example Response
 
Status: 200 OK

List Deleted Users
  • GET /api/v2/deleted_users.json

Lists deleted users, including permanently deleted users.

For permanently deleted users, all properties containing personal data, such as email and phone, are null. The name property is "Permanently Deleted User".

Returns a maximum of 100 users per page. See Pagination.

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

{
  "deleted_users": [
    {
      "id": 223443,
      "name": "Johnny Agent",
      ...
    },
    {
      "id": 8678530,
      "name": "James A. Rosen",
      ...
    }
  ]
}

Show Deleted User

GET /api/v2/deleted_users/{id}.json

These are users that have been deleted but not permanently yet. See Permanently Delete User.

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

{
  "deleted_user": {
    "id":   35436,
    "name": "Johnny Agent",
    ...
  }
}

Permanently Delete User

DELETE /api/v2/deleted_users/{id}.json

Before permanently deleting a user, you must delete the user first. See Delete User.

WARNING: Permanently deleting a user deletes all of their information. This information is not recoverable.

Allowed For
  • Agents, with restrictions on certain actions
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/deleted_users/{id}.json \
  -v -u {email_address}:{password} \
  -X DELETE
Example Response
 
Status: 200 OK

{
  "deleted_user": {
    "id":     9873843,
    "active": false,
    ...
  }
}
Permanent user deletion rate limit

You can permanently delete 700 users every 10 minutes. The rate limiting mechanism behaves as described in Rates Limits in the API introduction. Zendesk recommends that you obey the Retry-After header values.

Show Compliance Deletion Statuses

Returns the GDPR status for each user per area of compliance. A Zendesk area of compliance is typically a product like "support/explore" but can be more fine-grained for areas within the product lines.

GET /api/v2/users/{id}/compliance_deletion_statuses.json

Allowed For
  • Agents, with restrictions
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/{id}/compliance_deletion_statuses.json \
  -v -u {email_address}:{password} -d '{"application": "chat"}'
Example Responses

If user is not on the account

Status: 404
{
  "error":"RecordNotFound",
  "description":"Not found"
}

If user is not deleted

{
  "compliance_deletion_statuses": []
}

If user has compliance_deletion_statuses

Status: 200
{
  "compliance_deletion_statuses":
    [
      {
        "action": "request_deletion",
        "application": "all",
        "account_subdomain": "accountABC",
        "executer_id": 2000,
        "user_id": 1,
        "account_id": 33,
        "created_at": "2009-07-20T22:55:23Z"
      }
      {
        "action": "started",
        "application": "support",
        "account_subdomain": "accountABC",
        "executer_id": '',
        "user_id": 1,
        "account_id": 33,
        "created_at": "2009-07-20T22:55:29Z"
      }
      {
        "action": "complete",
        "application": "support",
        "account_subdomain": "accountABC",
        "executer_id": '',
        "user_id": 1,
        "account_id": 33,
        "created_at": "2009-07-20T22:57:02Z"
      }
      {
        "action": "started",
        "application": "chat",
        "account_subdomain": "accountABC",
        "executer_id": '',
        "user_id": 1,
        "account_id": 33,
        "created_at": "2009-07-21T02:51:18Z"
      }
    ]
}

Show the Currently Authenticated User

GET /api/v2/users/me.json

Allowed For:
  • Authenticated user
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/me.json \
  -v -u {email_address}:{password} -H "Content-Type: application/json"
Example Response
 
Status: 200

{
  "user": {
    "id":   35436,
    "name": "Roger Wilco",
    ...
  }
}

Set a User's Password

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

Allowed For
  • Admins

An admin can set a user's password only if the setting is enabled under Settings > Security > Global. The setting is off by default. Only the account owner can access and change this setting in Zendesk Support.

Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/password.json \
  -X POST -d '{"password": "newpassword"}' -H "Content-Type: application/json" \
  -v -u {email_address}:{password}
Example Response
 
Status: 200

Change Your Password

PUT /api/v2/users/{user_id}/password.json

Allowed For
  • Agents
  • End Users

You can only change your own password. Nobody can change the password of another user because it requires knowing the user's existing password. However, an admin can set a new password for another user without knowing the existing password. See "Set a User's Password" above.

Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/password.json \
  -X PUT -d '{"previous_password": "oldpassword", "password": "newpassword"}' \
  -v -u {email_address}:{password} -H "Content-Type: application/json"
Example Response
 
Status: 200

Get a list of password requirements

GET /api/v2/users/{user_id}/password/requirements.json

Allowed For
  • Agents
  • End Users
Using curl
 
curl https://{subdomain}.zendesk.com/api/v2/users/{user_id}/password/requirements.json \
  -v -u {email_address}:{password} -H "Content-Type: application/json"
Example Response
 
Status: 200

{
  "requirements": [
    "must be at least 5 characters",
    "must be different from email address"
  ]
}