User Fields

Zendesk Support allows admins to customize fields displayed on a User profile page. Basic text fields, date fields, as well as customizable dropdown and number fields are available. These fields are currently only visible to agents.

JSON Format

Custom fields have the following attributes:

Name Type Read-only Mandatory Comment
id integer yes no Automatically assigned upon creation
url string yes no The URL for this resource
key string no on create A unique key that identifies this custom field. This is used for updating the field and referencing in placeholders.
type string no yes Type of the custom field: "checkbox", "date", "decimal", "dropdown", "integer", "regexp", "text", or "textarea"
title string no yes The title of the custom field
raw_title string no no The dynamic content placeholder, if present, or the "title" value, if not. See Dynamic Content
description string no no User-defined description of this field's purpose
raw_description string no no The dynamic content placeholder, if present, or the "description" value, if not. See Dynamic Content
position integer no no Ordering of the field relative to other fields
active boolean no no If true, this field is available for use
system boolean yes no If true, only active and position values of this field can be changed
regexp_for_validation string no no Regular expression field only. The validation pattern for a field value to be deemed valid.
created_at date yes no The time the ticket field was created
updated_at date yes no The time of the last update of the ticket field
tag string no no Optional for custom field of type "checkbox"; not presented otherwise.
custom_field_options array no yes Required and presented for a custom field of type "dropdown"

List User Fields

GET /api/v2/user_fields.json

Returns a list of all 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 resource.

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

{
  "user_fields": [
    {
      "url": "https://company.zendesk.com/api/v2/user_fields/7.json",
      "id": 7,
      "type": "text",
      "key": "custom_field_1",
      "title": "Custom Field 1",
      "raw_title": "Custom Field 1",
      "description": "Description of Custom Field",
      "raw_description": "{{dc.my_description}}",
      "position": 9999,
      "active": true,
      "regexp_for_validation": null,
      "created_at": "2012-10-16T16:04:06Z",
      "updated_at": "2012-10-16T16:04:06Z"
    }
  ],
  "next_page": null,
  "previous_page": null,
  "count": 1
}

Show User Field

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

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

{
  "user_field": {
    "url": "https://company.zendesk.com/api/v2/user_fields/7.json",
    "id": 7,
    "type": "text",
    "key": "custom_field_1",
    "title": "Custom Field 1",
    "raw_title": "Custom Field 1",
    "description": "Description of Custom Field",
    "raw_description": "{{dc.my_description}}",
    "position": 9999,
    "active": true,
    "regexp_for_validation": null,
    "created_at": "2012-10-16T16:04:06Z",
    "updated_at": "2012-10-16T16:04:06Z"
  }
}

Create User Fields

POST /api/v2/user_fields.json

Types of custom fields that can be created are:

  • text (default when no "type" is specified)
  • textarea
  • checkbox
  • date
  • integer
  • decimal
  • regexp
  • tagger (custom dropdown)
Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/user_fields.json \
  -H "Content-Type: application/json" -X POST \
  -d '{"user_field": {"type": "text", "title": "Support description",
       "description": "This field describes the support plan this user has",
       "position": 0, "active": true, "key": "support_description"}}' \
  -v -u {email_address}:{password}
Example Response
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/user_fields/{id}.json

{
  "user_field": {
    "url": "https://company.zendesk.com/api/v2/user_fields/75.json",
    "id": 75,
    "type": "text",
    "key": "support_description",
    "title": "Support description",
    "raw_title": "Support description",
    "description": "This field describes the support plan this user has",
    "raw_description": "This field describes the support plan this user has",
    "position": 0,
    "active": true,
    "regexp_for_validation": null,
    "created_at": "2013-02-27T20:35:55Z",
    "updated_at": "2013-02-27T20:35:55Z"
  }
}

Update User Fields

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

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

{
  "user_field": {
    "url": "https://company.zendesk.com/api/v2/user_fields/75.json",
    "id": 75,
    "type": "text",
    "key": "support_description",
    "title": "Support description",
    "raw_title": "Support description",
    "description": "This field describes the support plan this user has",
    "raw_description": "This field describes the support plan this user has",
    "position": 0,
    "active": true,
    "regexp_for_validation": null,
    "created_at": "2013-02-27T20:35:55Z",
    "updated_at": "2013-02-27T20:35:55Z"
  }
}

Update a Dropdown (Tagger) Field

Dropdown fields return an array of custom_field_options which specify the name, value and order of the list of dropdown options. Understand the following behavior when updating a dropdown 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 users.
  • 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.
Using curl
curl https://{subdomain}.zendesk.com/api/v2/user_fields/{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}:{password}

Delete User Field

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

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

Reorder User Field

PUT /api/v2/user_fields/reorder.json

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/user_fields/reorder.json -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X PUT -d '{ "user_field_ids": [3, 4] }'
Example Response
Status: 200 OK

List User Field Options

GET /api/v2/user_fields/{field_id}/options.json

Returns a list of all custom User Field Options for the given dropdown User Field.

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

{
    "count": 2,
    "custom_field_options": [
        {
            "id": 10000,
            "name": "Apples",
            "position": 0,
            "raw_name": "Apples",
            "url": "http://{subdomain}.zendesk.com/api/v2/user_fields/1/options/10000.json",
            "value": "apple"
        },
        {
            "id": 10001,
            "name": "Bananas",
            "position": 1,
            "raw_name": "Bananas",
            "url": "http://{subdomain}.zendesk.com/api/v2/user_fields/1/options/10001.json",
            "value": "banana"
        }
     ],
     "next_page": null,
     "previous_page": null
}

Show a User Field Option

GET /api/v2/user_fields/{field_id}/options/{id}.json

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

{
    "custom_field_option": {
        "id": 10001,
        "name": "Bananas",
        "position": 1,
        "raw_name": "Bananas",
        "url": "http://{subdomain}.zendesk.com/api/v2/user_fields/1/options/10001.json",
        "value": "banana"
    }
}

Create or Update a User Field Option

POST /api/v2/user_fields/{field_id}/options.json

Creates a new or updates an existing option for the given dropdown 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.

Allowed For
  • Admins
Using curl (Create)
curl https://{subdomain}.zendesk.com/api/v2/user_fields/{field_id}/options.json \
  -H "Content-Type: application/json" -X POST \
  -d '{"custom_field_option": {"name": "Grapes", "position": 2, "value": "grape"}}' \
  -v -u {email_address}:{password}
Example Response
Status: 201 Created

{
    "custom_field_option": {
        "id": 10002,
        "name": "Grapes",
        "position": 2,
        "raw_name": "Grapes",
        "url": "http://{subdomain}.zendesk.com/api/v2/user_fields/1/options/10002.json",
        "value": "grape"
    }
}
Using curl (Update)
curl https://{subdomain}.zendesk.com/api/v2/user_fields/{field_id}/options.json \
  -H "Content-Type: application/json" -X POST \
  -d '{"custom_field_option": {"id": 10002, "name": "Pineapples", "position": 2, "value": "pineapple"}}' \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
    "custom_field_option": {
        "id": 10002,
        "name": "Pineapples",
        "position": 2,
        "raw_name": "Pineapples",
        "url": "http://{subdomain}.zendesk.com/api/v2/user_fields/1/options/10002.json",
        "value": "pineapple"
    }
}

Delete User Field Option

DELETE /api/v2/user_fields/{field_id}/options/{id}.json

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