Organization Fields

Zendesk Support allows admins to customize fields displayed on an Organization 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 Organization Fields

GET /api/v2/organization_fields.json

Returns a list of all custom Organization Fields in your account. Fields are returned in the order that you specify in your Organization Fields configuration in Zendesk Support. Clients should cache this resource for the duration of their API usage and map the key for each Organization Field to the values returned under the organization_fields attribute on the Organization resource.

Allowed For

Agents

Using curl

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

Example Response

Status: 200 OK

{
  "organization_fields": [
    {
      "url": "https://company.zendesk.com/api/v2/organization_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 Organization Field

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

Allowed For

Agents

Using curl

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

Example Response

Status: 200 OK

{
  "organization_fields": [
    {
      "url": "https://company.zendesk.com/api/v2/organization_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
}

Create Organization Fields

POST /api/v2/organization_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/organization_fields.json \
  -H "Content-Type: application/json" -X POST \
  -d '{"organization_field": {"type": "text", "title": "Support description",
       "description": "This field describes the support plan this organization 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/organization_fields/{id}.json

{
  "organization_field": {
    "url": "https://company.zendesk.com/api/v2/organization_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 organization has",
    "raw_description": "This field describes the support plan this organization has",
    "position": 0,
    "active": true,
    "regexp_for_validation": null,
    "created_at": "2013-02-27T20:35:55Z",
    "updated_at": "2013-02-27T20:35:55Z"
  }
}

Update Organization Fields

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

Allowed For

Admins

Using curl

curl https://{subdomain}.zendesk.com/api/v2/organization_fields/{id}.json \
  -H "Content-Type: application/json" -X PUT \
  -d '{ "organization_field": { "title": "Support description" }}' \
  -v -u {email_address}:{password}

Example Response

Status: 200 OK
Location: https://{subdomain}.zendesk.com/api/v2/organization_fields/75.json

{
  "organization_field": {
    "url": "https://company.zendesk.com/api/v2/organization_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 organization has",
    "raw_description": "This field describes the support plan this organization has",
    "position": 0,
    "active": true,
    "regexp_for_validation": null,
    "created_at": "2013-02-27T20:35:55Z",
    "updated_at": "2013-02-27T20:35:55Z"
  }
}

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

Using curl

curl https://{subdomain}.zendesk.com/api/v2/organization_fields/{id}.json \
  -H "Content-Type: application/json" -X PUT \
  -d '{"organization_field": {"custom_field_options": [{"id": 124, "name": "Option 2", "value": "option_2"}, {"id": 123, "name": "Option 1", "value": "option_1"}, {"id": 125, "name": "Option 3", "value": "option_3"}]}}' \
  -v -u {email_address}:{password}

Delete Organization Field

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

Allowed For

Admins

Using curl

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

Example Response

Status: 200 OK

Reorder Organization Field

PUT /api/v2/organization_fields/reorder.json

Allowed For

Admins

Using curl

curl https://{subdomain}.zendesk.com/api/v2/organization_fields/reorder.json \
  -v -u {email_address}:{password} -X PUT -d '{ "organization_field_ids": [3, 4] }' -H "Content-Type: application/json"

Example Response

Status: 200 OK