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 thename
andvalue
- To update an existing option, pass its
id
along with thename
andvalue
- 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