The Zendesk User Fields API lets you programmatically define and manage the custom attributes you store on users in Zendesk Support. You can list, create, update, and delete user fields (such as text, number, date, checkbox, or dropdown), which become part of your user schema and appear on user profiles for agents.
openapi: 3.1.0
info:
version: "1.0"
title: Zendesk User Fields
description: Needs a description.
paths:
/api/v2/user_fields:
get:
operationId: ListUserFields
tags:
- User Fields
summary: Zendesk Get Api V2 User_fields
description: >
Returns a list of custom user fields in your account. Fields are
returned in the order that you specify in your user fields configuration
in Zendesk Support. Clients should cache this resource for the duration
of their API usage and map the key for each User Field to the values
returned under the `user_fields` attribute on the
[User](/api-reference/ticketing/users/users/) resource.
#### Pagination
* Cursor pagination (recommended)
* Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Allowed For
* Agents
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/UserFieldsResponse'
examples:
default:
$ref: '#/components/examples/UserFieldsResponseExample'
post:
operationId: CreateUserField
tags:
- User Fields
summary: Zendesk Post Api V2 User_fields
description: >
Creates any of the following custom field types:
* text (default when no "type" is specified)
* textarea
* checkbox
* date
* integer
* decimal
* regexp
* dropdown
* lookup
* multiselect
See [About custom field
types](https://support.zendesk.com/hc/en-us/articles/203661866) in
Zendesk help.
#### Allowed For
* Admins
responses:
'201':
description: Created response
content:
application/json:
schema:
$ref: '#/components/schemas/UserFieldResponse'
examples:
default:
$ref: '#/components/examples/UserFieldCreateResponseExample'
/api/v2/user_fields/{user_field_id}:
parameters:
- $ref: '#/components/parameters/UserFieldId'
get:
operationId: ShowUserField
tags:
- User Fields
summary: Zendesk Get Api V2 User_fields User_field_id
description: |
#### Allowed for
* Agents
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/UserFieldResponse'
examples:
default:
$ref: '#/components/examples/UserFieldResponseExample'
put:
operationId: UpdateUserField
tags:
- User Fields
summary: Zendesk Put Api V2 User_fields User_field_id
description: >
#### Updating a Dropdown (Tagger) or Multiselect Field
Dropdown and multiselect fields return an array of
`custom_field_options` which specify the name, value, and order of the
list of dropdown or multiselect options.
Understand the following behavior when updating a dropdown or
multiselect field:
- All options must be passed on update. Options that are not passed will
be removed. As a result, these values will be removed from any
organizations.
- To create a new option, pass a null `id` along with `name` and
`value`.
- To update an existing option, pass its `id` along with `name` and
`value`.
- To re-order an option, reposition it in the `custom_field_options`
array relative to the other options.
- To remove an option, omit it from the list of options upon update.
#### Example Request
```bash
curl
https://{subdomain}.zendesk.com/api/v2/user_fields/{user_field_id}.json
\
-H "Content-Type: application/json" -X PUT \
-d '{"user_field": {"custom_field_options": [{"id": 124, "name": "Option 2", "value": "option_2"}, {"id": 123, "name": "Option 1", "value": "option_1"}, {"id": 125, "name": "Option 2", "value": "option_3"}]}}' \
-v -u {email_address}/token:{api_token}
```
#### Allowed for
* Admins
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/UserFieldResponse'
examples:
default:
$ref: '#/components/examples/UserFieldUpdateResponseExample'
delete:
operationId: DeleteUserField
tags:
- User Fields
summary: Zendesk Delete Api V2 User_fields User_field_id
description: |
#### Allowed for
* Admins
responses:
'204':
description: No Content response
/api/v2/user_fields/{user_field_id}/options:
parameters:
- $ref: '#/components/parameters/UserFieldId'
get:
operationId: ListUserFieldOptions
tags:
- User Fields
summary: Zendesk Get Api V2 User_fields User_field_id Options
description: >
Returns a list of custom user field options for the given dropdown user
field.
#### Pagination
* Cursor pagination (recommended)
* Offset pagination
See [Pagination](/api-reference/introduction/pagination/).
Returns a maximum of 100 records per page.
#### Allowed For
* Agents
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldOptionsResponse'
examples:
default:
$ref: '#/components/examples/CustomUserFieldOptionsResponseExample'
post:
operationId: CreateOrUpdateUserFieldOption
tags:
- User Fields
summary: Zendesk Post Api V2 User_fields User_field_id Options
description: >
Creates a new option or updates an existing option for the given
drop-down user field.
To update an option, include the id of the option in the
`custom_field_option` object. Example: `{"custom_field_option": {"id":
10002, "name": "Pineapples", ... }`. If an option exists for the given
ID, the option will be updated. Otherwise, a new option will be created.
#### Response
Returns one of the following status codes:
- 200 with `Location: /api/v2/user_fields/{user_field_id}/options.json`
if the user field option already exists in the database
- 201 with `Location: /api/v2/user_fields/{user_field_id}/options.json`
if the user field option is new
#### Allowed For
* Admins
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldOptionResponse'
examples:
default:
$ref: >-
#/components/examples/CustomUserFieldOptionUpdateResponseExample
'201':
description: Created response
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldOptionResponse'
examples:
default:
$ref: >-
#/components/examples/CustomUserFieldOptionCreateResponseExample
/api/v2/user_fields/{user_field_id}/options/{user_field_option_id}:
parameters:
- $ref: '#/components/parameters/UserFieldId'
- $ref: '#/components/parameters/UserFieldOptionId'
get:
operationId: ShowUserFieldOption
tags:
- User Fields
summary: Zendesk Get Api V2 User_fields User_field_id Options User_field_option_id
description: |
#### Allowed for
* Agents
responses:
'200':
description: Success response
content:
application/json:
schema:
$ref: '#/components/schemas/CustomFieldOptionResponse'
examples:
default:
$ref: '#/components/examples/CustomUserFieldOptionResponseExample'
delete:
operationId: DeleteUserFieldOption
tags:
- User Fields
summary: Zendesk Delete Api V2 User_fields User_field_id Options User_field_option_id
description: |
#### Allowed for
* Admins
responses:
'204':
description: No Content response
/api/v2/user_fields/reorder:
put:
operationId: ReorderUserField
tags:
- User Fields
summary: Zendesk Put Api V2 User_fields Reorder
description: |
#### Allowed For
* Admins
responses:
'200':
description: Success response
content:
application/json:
schema:
type: string
description: Empty response
example: ''
example: ''
components:
schemas:
UserFieldsResponse:
type: object
properties:
count:
type: integer
description: Total count of records retrieved
readOnly: true
next_page:
type: string
description: URL of the next page
nullable: true
readOnly: true
previous_page:
type: string
description: URL of the previous page
nullable: true
readOnly: true
user_fields:
type: array
items:
$ref: '#/components/schemas/UserFieldObject'
UserFieldResponse:
type: object
properties:
user_field:
$ref: '#/components/schemas/UserFieldObject'
CustomFieldOptionsResponse:
type: object
properties:
count:
type: integer
description: Total count of records retrieved
readOnly: true
custom_field_options:
type: array
items:
$ref: '#/components/schemas/CustomFieldOptionObject'
next_page:
type: string
description: URL of the next page
nullable: true
readOnly: true
previous_page:
type: string
description: URL of the previous page
nullable: true
readOnly: true
CustomFieldOptionResponse:
type: object
properties:
custom_field_option:
$ref: '#/components/schemas/CustomFieldOptionObject'
tags:
- name: User Fields