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

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 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 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.

Use the Tickets API to list:

• tickets requested by a user
• tickets on which a user is cc'ed

Use the Help Center API to list:

• articles and article comments created by a user
• community posts and post comments created by a user

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

You can specify a user's primary email address when you create the user. See Specifying email and verified attributes

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

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",
    ...
  }
}

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.

The phone number should comply with the E.164 international telephone numbering plan. Example +15551234567. 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.

{
  "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":                 "[email protected]",
  "phone":                 "+15551234567",
  "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"
  }
}

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

{
  "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":                 "[email protected]",
  "phone":                 "+15551234567",
  "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,
      }
    ]
  }
}

The JSON returned by the user related information endpoint includes the following properties.

Note: Depending on the user's permissions, the count results may not match the actual number of tickets returned.

It also includes the following additional properties about the Web portal, the self-help solution offered by Zendesk before Help Center. The Web portal is deprecated but the API still returns data about the user's activity if they used it. See the Help Center API to get comparable data for Help Center. Articles, posts, comments, subscriptions, and votes each have a list-by-user endpoint.

{
  "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,
  }
}

• 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.

• Admins, Agents and Light Agents

curl https://{subdomain}.zendesk.com/api/v2/users.json \
  -v -u {email_address}:{password}

• 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}

Status: 200

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

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

• Agents

curl https://{subdomain}.zendesk.com/api/v2/users/{id}.json \
  -v -u {email_address}:{password}

Status: 200

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

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 up to 100 user ids or external ids.

• Agents

curl https://{subdomain}.zendesk.com/api/v2/users/show_many.json?ids=1,2,3 \
  -v -u {email_address}:{password}

Status: 200 OK

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

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

See JSON Format for User Related Information.

• Agents

curl https://{subdomain}.zendesk.com/api/v2/users/{id}/related.json \
  -v -u {email_address}:{password}

Status: 200

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

POST /api/v2/users.json

• Agents, with restrictions on certain actions

curl https://{subdomain}.zendesk.com/api/v2/users.json \
  -d '{"user": {"name": "Roger Wilco", "email": "[email protected]"}}' \
  -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.

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.

curl https://{subdomain}.zendesk.com/api/v2/users.json \
  -d '{"user": {"name": "Roger Wilco", "email": "rog[email protected]", "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": "[email protected]", "organization": {"name": "VIP Customers"}}}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}

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": "[email protected]"}, {"type": "twitter", "value": "tester84" }]}}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}

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.

• Agents, with restrictions on certain actions

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": "[email protected]"}}' \
  -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": "[email protected]"}}' \
  -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": "[email protected]", "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.

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",
    ...
  }
}

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.

• Agents, with restrictions on certain actions

curl https://{subdomain}.zendesk.com/api/v2/users/create_or_update_many.json \
  -d '{"users": [{"name": "Roger Wilco", "email": "[email protected]", "role": "agent"}, {"external_id": "account_54321", "name": "Woger Rilco", "email": "[email protected]", "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.

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.

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

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

• Verified end users

curl https://{subdomain}.zendesk.com/api/v2/users/me/merge.json \
  -d '{"user": {"password": "foo1234", "email": "[email protected]"}}' \
  -H "Content-Type: application/json" -X PUT \
  -v -u {email_address}:{password}

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

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

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.

• Admins

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}

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

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

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 [email protected] for assistance.

• Agents, with restrictions on certain actions

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": "[email protected]",
      "organization_id": 567812345
    },
    ...
  ]
}

curl https://{subdomain}.zendesk.com/api/v2/users/create_many.json \
  -d '{"users": [{"name": "Roger Wilco", "email": "[email protected]", "role": "agent"}, {"name": "Woger Rilco", "email": "[email protected]", "role": "admin"}]}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}

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.

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

• Agents, with restrictions on certain actions

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

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}

Status: 200 OK

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

• If both email and verified attributes are provided, the provided email is added to the user as a secondary email with the verified property set to the specified value. The primary email remains unmodified
• If only email is provided, the provided email is added to the user as a secondary email with the verified property set property set to false. The primary email remains unmodified
• If only verified is provided, the verified property of the primary email identity is set to the given value

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.

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
  }
}

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 }
  ]
}

• Agents, with restrictions

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

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}

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.

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.

• Admins

curl https://{subdomain}.zendesk.com/api/v2/users/destroy_many.json?ids=1,2,3 \
  -v -u {email_address}:{password} -X DELETE

Status: 200 OK

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.

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}

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

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

• Agents, with restrictions on certain actions

curl https://{subdomain}.zendesk.com/api/v2/users/{id}.json \
  -v -u {email_address}:{password} \
  -X DELETE

Status: 200 OK

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

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".

The query parameter supports the Zendesk search syntax for more advanced user searches. See the Search API.

The external_id parameter does not support the search syntax. It only accepts ids.

• Admins, Agents and Light Agents

curl https://{subdomain}.zendesk.com/api/v2/users/search.json?query=gil \
  -v -u {email_address}:{password}

Status: 200

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

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.

• Agents

curl https://{subdomain}.zendesk.com/api/v2/users/autocomplete.json?name=gil \
  -u {email_address}:{password}

Status: 200

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

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.

Uploading a local file:

curl https://{subdomain}.zendesk.com/api/v2/users/{id}.json \
  -F "user[photo][uploaded_data][email protected]/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

POST /api/v2/users/request_create.json

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

• Agents

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

Status: 200 OK

• GET /api/v2/deleted_users.json

Returns deleted users, including permanently deleted users, up to a maximum of 100 users per page. See Pagination.

If the results contains permanently deleted users, the users' properties that normally contain personal data, such as email and phone, are null. The name property is "Permanently Deleted User".

• Agents

curl https://{subdomain}.zendesk.com/api/v2/deleted_users.json \
  -v -u {email_address}:{password}

Status: 200

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

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

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

• Agents

curl https://{subdomain}.zendesk.com/api/v2/deleted_users/{id}.json \
  -v -u {email_address}:{password}

Status: 200

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

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.

• Agents, with restrictions on certain actions

curl https://{subdomain}.zendesk.com/api/v2/deleted_users/{id}.json \
  -v -u {email_address}:{password} \
  -X DELETE

Status: 200 OK

{
  "deleted_user": {
    "id":     9873843,
    "active": false,
    ...
  }
}

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.

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

• Agents, with restrictions

curl https://{subdomain}.zendesk.com/api/v2/users/{id}/compliance_deletion_statuses.json \
  -v -u {email_address}:{password} -d '{"application": "chat"}'

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"
      }
    ]
}

GET /api/v2/users/me.json

• Anonymous users

curl https://{subdomain}.zendesk.com/api/v2/users/me.json \
  -v -u {email_address}:{password} -H "Content-Type: application/json"

Status: 200

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