Organization Fields

Zendesk Support allows admins to customize fields displayed on an Organization page. Basic text fields, date fields, as well as customizable drop-down and number fields are available. These fields are currently only visible to agents.

JSON Format

Organization Fields are represented as JSON objects with the following properties:

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

Example

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

List Organization Fields

GET /api/v2/organization_fields

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

Pagination

Cursor pagination (recommended)
Offset pagination

See Pagination.

Returns a maximum of 100 records per page.

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

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

Create Organization Field

POST /api/v2/organization_fields

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

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

Reorder Organization Field

PUT /api/v2/organization_fields/reorder

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

Show Organization Field

GET /api/v2/organization_fields/{organization_field_id}

Allowed for

Agents

Parameters

Name	Type	In	Required	Description
organization_field_id	integer	Path	true	The ID of the organization field

Using curl

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

Example Response

Status 200 OK

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

Update Organization Field

PUT /api/v2/organization_fields/{organization_field_id}

Updating a Drop-down (Tagger) Field

Drop-down fields return an array of custom_field_options which specify the name, value, and order of drop-down options. When updating a drop-down field, note the following information:

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 the name and value
To update an existing option, pass its id along with the name and value
To reorder 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

curl https://{subdomain}.zendesk.com/api/v2/organization_fields/{organization_field_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}

Allowed for

Admins

Parameters

Name	Type	In	Required	Description
organization_field_id	integer	Path	true	The ID of the organization field

Using curl

curl https://{subdomain}.zendesk.com/api/v2/organization_fields/{organization_field_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

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

Delete Organization Field

DELETE /api/v2/organization_fields/{organization_field_id}

Allowed for

Admins

Parameters

Name	Type	In	Required	Description
organization_field_id	integer	Path	true	The ID of the organization field

Using curl

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

Example Response

Status 204 No Content