Ticket Forms

Ticket forms allow an admin to define a subset of ticket fields for display to both agents and end users.

Ticket forms are only available on Enterprise accounts or accounts with the Productivity Pack add-on.

JSON Format

Ticket Forms are represented as JSON objects which have the following keys:

Name Type Read-only Mandatory Comment
name string no yes The name of the form
raw_name string no no The dynamic content placeholder, if present, or the "name" value, if not. See Dynamic Content
display_name string no no The name of the form that is displayed to an end user
raw_display_name string no no The dynamic content placeholder, if present, or the "display_name" value, if not. See Dynamic Content
position integer no no The position of this form among other forms in the account, i.e. dropdown
active boolean no no If the form is set as active
end_user_visible boolean no no Is the form visible to the end user
default boolean no no Is the form the default form for this account
ticket_field_ids array no no ids of all ticket fields which are in this ticket form. The products use the order of the ids to show the field values in the tickets. See Field limits
in_all_brands boolean no no Is the form available for use in all brands on this account
restricted_brand_ids array yes no ids of all brands that this ticket form is restricted to
agent_conditions array no no Array of condition sets for agent workspaces
end_user_conditions array no no Array of condition sets for end user products

Warning: Sending an empty array [] for agent_conditions or end_user_conditions will delete the conditions.

Example
{
  "id":                    47,
  "url":                   "https://company.zendesk.com/api/v2/ticket_forms/47.json",
  "name":                  "Snowboard Problem",
  "raw_name":              "Snowboard Problem",
  "display_name":          "Snowboard Damage",
  "raw_display_name":      "{{dc.my_display_name}}",
  "end_user_visible":      true,
  "position":              9999,
  "ticket_field_ids":      [ 2, 4, 5, 10, 100, 101, 102, 200 ],
  "active":                true,
  "default":               true,
  "in_all_brands":         false,
  "restricted_brand_ids":  [ 47, 33, 22 ],
   "agent_conditions": [
     {
       "parent_field_id": 100,
       "value": "matching_value",
       "child_fields": [
         {
           "id": 101,
           "is_required": false,
           "required_on_statuses": {
             "type": "SOME_STATUSES",
             "statuses": ["new", "open", "pending", "hold"]
           }
         },
         {
           "id": 200,
           "is_required": true,
           "required_on_statuses": {
             "type": "SOME_STATUSES",
             "statuses": ["solved"]
           }
         }
       ]
     },
     {
       "parent_field_id": 101,
       "value": "matching_value_2",
       "child_fields": [
         {
           "id": 102,
           "is_required": true,
           "required_on_statuses": {
             "type": "ALL_STATUSES",
           }
         },
         {
           "id": 200,
           "is_required": false,
           "required_on_statuses": {
             "type": "NO_STATUSES",
           }
         }
       ]
     }
   ],
   "end_user_conditions": [
     {
       "parent_field_id": 100,
       "value": "matching_value",
       "child_fields": [ {"id": 101, "is_required": true } ]
     },
     {
       "parent_field_id": 200,
       "value": "matching_value",
       "child_fields": [ {"id": 202, "is_required": false } ]
     }
   ],
  "created_at":            "2012-04-02T22:55:29Z",
  "updated_at":            "2012-04-02T22:55:29Z"
}

List Ticket Forms

GET /api/v2/ticket_forms.json

Returns a list of all ticket forms for your account if accessed as an admin or agent. End users only see ticket forms that have end_user_visible set to true.

Allowed For
  • Anyone
Available Parameters

You can filter the results with any combination of the following query string parameters.

Name Type Comment
active boolean true returns active ticket forms; false returns inactive ticket forms. If not present, returns both
end_user_visible boolean true returns ticket forms where end_user_visible; false returns ticket forms that are not end-user visible. If not present, returns both
fallback_to_default boolean true returns the default ticket form when the criteria defined by the parameters results in a set without active and end-user visible ticket forms
associated_to_brand boolean true returns the ticket forms of the brand specified by the url's subdomain
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_forms.json?active=true \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "ticket_forms": [
    {
      "id":                    47,
      "url":                   "https://company.zendesk.com/api/v2/ticket_forms/47.json",
      "name":                  "Snowboard Problem",
      "raw_name":              "Snowboard Problem",
      "display_name":          "Snowboard Damage",
      "raw_display_name":      "{{dc.my_display_name}}",
      "end_user_visible":      true,
      "position":              9999,
      "active":                true,
      "default":               true,
      "in_all_brands":         false,
      "restricted_brand_ids":  [ 1,4,6,12,34 ],
      "ticket_field_ids":      [ 2,4,5,32,44 ],
      "agent_conditions":      [
                                 {
                                   "parent_field_id": 5,
                                   "value": "matching_value_1",
                                   "child_fields": [
                                     {
                                       "id": 44,
                                       "is_required": false,
                                       "required_on_statuses": {
                                         "type": "SOME_STATUSES",
                                         "statuses": ["new", "open", "pending", "hold"]
                                       }
                                     },
                                     {
                                       "id": 32,
                                       "is_required": true,
                                       "required_on_statuses": {
                                         "type": "SOME_STATUSES",
                                         "statuses": ["solved"]
                                       }
                                     }
                                   ]
                                 },
                                 {
                                   "parent_field_id": 32,
                                   "value": "matching_value_2",
                                   "child_fields": [
                                     {
                                       "id": 44,
                                       "is_required": true,
                                       "required_on_statuses": {
                                         "type": "ALL_STATUSES",
                                       }
                                     },
                                     {
                                       "id": 32,
                                       "is_required": false,
                                       "required_on_statuses": {
                                         "type": "NO_STATUSES",
                                       }
                                     }
                                   ]
                                 }
                               ],
       "end_user_conditions":  [
                                 {
                                   "parent_field_id": 5,
                                   "value": "matching_value_1",
                                   "child_fields": [ { "id": 32, "is_required": true } ]
                                 },
                                 {
                                   "parent_field_id": 32,
                                   "value": "matching_value_2",
                                   "child_fields": [ { "id": 44, "is_required": false } ]
                                 }
                               ],
      "created_at":            "2012-04-02T22:55:29Z",
      "updated_at":            "2012-04-02T22:55:29Z"
    }
  ]
}

Create Ticket Forms

POST /api/v2/ticket_forms.json

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_forms.json \
  -H "Content-Type: application/json" -X POST \
  -d '
{
  "ticket_form": {
    "name": "Snowboard Problem",
    "end_user_visible": true,
    "display_name": "Snowboard Damage",
    "position": 9999,
    "active" : true,
    "in_all_brands": false,
    "restricted_brand_ids": [ 1,4,6,12,34 ],
    "ticket_field_ids": [ 2,4,5,32,44 ],
    "agent_conditions":    [
                             {
                               "parent_field_id": 5,
                               "value": "matching_value_1",
                               "child_fields": [
                                 {
                                   "id": 44,
                                   "is_required": false,
                                   "required_on_statuses": {
                                     "type": "SOME_STATUSES",
                                     "statuses": ["new", "open", "pending", "hold"]
                                   }
                                 },
                                 {
                                   "id": 32,
                                   "is_required": true,
                                   "required_on_statuses": {
                                     "type": "SOME_STATUSES",
                                     "statuses": ["solved"]
                                   }
                                 }
                               ]
                             },
                             {
                               "parent_field_id": 32,
                               "value": "matching_value_2",
                               "child_fields": [
                                 {
                                   "id": 44,
                                   "is_required": true,
                                   "required_on_statuses": {
                                     "type": "ALL_STATUSES",
                                   }
                                 },
                                 {
                                   "id": 32,
                                   "is_required": false,
                                   "required_on_statuses": {
                                     "type": "NO_STATUSES",
                                   }
                                 }
                               ]
                             }
                           ],
    "end_user_conditions": [
                             {
                               "parent_field_id": 5,
                               "value": "matching_value_1",
                               "child_fields": [ { "id": 32, "is_required": true } ]
                             },
                             {
                               "parent_field_id": 32,
                               "value": "matching_value_2",
                               "child_fields": [ { "id": 44, "is_required": false } ]
                             }
                           ],
    "default" : false
  }
}' \
  -v -u {email_address}:{password}
Example Response
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/ticket_forms/{id}.json

{
  "ticket_form": {
    "id":                    47,
    "url":                   "https://company.zendesk.com/api/v2/ticket_forms/47.json",
    "name":                  "Snowboard Problem",
    "raw_name":              "Snowboard Problem",
    "display_name":          "Snowboard Damage",
    "raw_display_name":      "Snowboard Damage",
    "end_user_visible":      true,
    "position":              9999,
    "active":                true,
    "default":               false,
    "in_all_brands":         false,
    "restricted_brand_ids":  [ 1,4,6,12,34 ],
    "ticket_field_ids":      [ 2,4,5,32,44 ],
    "agent_conditions":      [
                               {
                                 "parent_field_id": 5,
                                 "value": "matching_value_1",
                                 "child_fields": [
                                   {
                                     "id": 44,
                                     "is_required": false,
                                     "required_on_statuses": {
                                       "type": "SOME_STATUSES",
                                       "statuses": ["new", "open", "pending", "hold"]
                                     }
                                   },
                                   {
                                     "id": 32,
                                     "is_required": true,
                                     "required_on_statuses": {
                                       "type": "SOME_STATUSES",
                                       "statuses": ["solved"]
                                     }
                                   }
                                 ]
                               },
                               {
                                 "parent_field_id": 32,
                                 "value": "matching_value_2",
                                 "child_fields": [
                                   {
                                     "id": 44,
                                     "is_required": true,
                                     "required_on_statuses": {
                                       "type": "ALL_STATUSES",
                                     }
                                   },
                                   {
                                     "id": 32,
                                     "is_required": false,
                                     "required_on_statuses": {
                                       "type": "NO_STATUSES",
                                     }
                                   }
                                 ]
                               }
                             ],
    "end_user_conditions":   [
                               {
                                 "parent_field_id": 5,
                                 "value": "matching_value_1",
                                 "child_fields": [ { "id": 32, "is_required": true } ]
                               },
                               {
                                 "parent_field_id": 32,
                                 "value": "matching_value_2",
                                 "child_fields": [ { "id": 44, "is_required": false } ]
                               }
                             ],
    "created_at":            "2012-04-02T22:55:29Z",
    "updated_at":            "2012-04-02T22:55:29Z"
  }
}

Show Ticket Form

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

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

{
  "ticket_form": {
    "id":                    47,
    "url":                   "https://company.zendesk.com/api/v2/ticket_forms/47.json",
    "name":                  "Snowboard Problem",
    "raw_name":              "Snowboard Problem",
    "display_name":          "Snowboard Damage",
    "raw_display_name":      "{{dc.my_display_name}}",
    "end_user_visible":      true,
    "position":              9999,
    "active":                true,
    "default":               true,
    "in_all_brands":         false,
    "restricted_brand_ids":  [ 1,4,6,12,34 ],
    "ticket_field_ids":      [ 2,4,5,32,44 ],
    "agent_conditions":      [
                               {
                                 "parent_field_id": 5,
                                 "value": "matching_value_1",
                                 "child_fields": [
                                   {
                                     "id": 44,
                                     "is_required": false,
                                     "required_on_statuses": {
                                       "type": "SOME_STATUSES",
                                       "statuses": ["new", "open", "pending", "hold"]
                                     }
                                   },
                                   {
                                     "id": 32,
                                     "is_required": true,
                                     "required_on_statuses": {
                                       "type": "SOME_STATUSES",
                                       "statuses": ["solved"]
                                     }
                                   }
                                 ]
                               },
                               {
                                 "parent_field_id": 32,
                                 "value": "matching_value_2",
                                 "child_fields": [
                                   {
                                     "id": 44,
                                     "is_required": true,
                                     "required_on_statuses": {
                                       "type": "ALL_STATUSES",
                                     }
                                   },
                                   {
                                     "id": 32,
                                     "is_required": false,
                                     "required_on_statuses": {
                                       "type": "NO_STATUSES",
                                     }
                                   }
                                 ]
                               }
                             ],
    "end_user_conditions":   [
                               {
                                 "parent_field_id": 5,
                                 "value": "matching_value_1",
                                 "child_fields": [ { "id": 32, "is_required": true } ]
                               },
                               {
                                 "parent_field_id": 32,
                                 "value": "matching_value_2",
                                 "child_fields": [ { "id": 44, "is_required": false } ]
                               }
                             ],
    "created_at":            "2012-04-02T22:55:29Z",
    "updated_at":            "2012-04-02T22:55:29Z"
  }
}

Show Many Ticket Forms

GET /api/v2/ticket_forms/show_many.json?ids={ids}

Accepts a comma separated list of ticket form ids returning up to 100 records. This endpoint is meant to be used primarily by the mobile SDKs and the Web Widgets. See Zendesk Embeddables.

Allowed For:
  • Anyone
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_forms/show_many.json?ids=1,2,3 \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "ticket_forms": [
    {
      "id":                    47,
      "url":                   "https://company.zendesk.com/api/v2/ticket_forms/47.json",
      "name":                  "Snowboard Problem",
      "raw_name":              "Snowboard Problem",
      "display_name":          "Snowboard Damage",
      "raw_display_name":      "{{dc.my_display_name}}",
      "end_user_visible":      true,
      "position":              9999,
      "active":                true,
      "default":               true,
      "in_all_brands":         false,
      "restricted_brand_ids":  [ 1,4,6,12,34 ],
      "ticket_field_ids":      [ 2,4,5,32,44 ],
      "agent_conditions":      [
                                 {
                                   "parent_field_id": 5,
                                   "value": "matching_value_1",
                                   "child_fields": [
                                     {
                                       "id": 44,
                                       "is_required": false,
                                       "required_on_statuses": {
                                         "type": "SOME_STATUSES",
                                         "statuses": ["new", "open", "pending", "hold"]
                                       }
                                     },
                                     {
                                       "id": 32,
                                       "is_required": true,
                                       "required_on_statuses": {
                                         "type": "SOME_STATUSES",
                                         "statuses": ["solved"]
                                       }
                                     }
                                   ]
                                 },
                                 {
                                   "parent_field_id": 32,
                                   "value": "matching_value_2",
                                   "child_fields": [
                                     {
                                       "id": 44,
                                       "is_required": true,
                                       "required_on_statuses": {
                                         "type": "ALL_STATUSES",
                                       }
                                     },
                                     {
                                       "id": 32,
                                       "is_required": false,
                                       "required_on_statuses": {
                                         "type": "NO_STATUSES",
                                       }
                                     }
                                   ]
                                 }
                               ],
      "end_user_conditions":   [
                                  {
                                    "parent_field_id": 5,
                                    "value": "matching_value_1",
                                    "child_fields": [ { "id": 32, "is_required": true } ]
                                  },
                                  {
                                    "parent_field_id": 32,
                                    "value": "matching_value_2",
                                    "child_fields": [ { "id": 44, "is_required": false } ]
                                  }
                                ],
      "created_at":            "2012-04-02T22:55:29Z",
      "updated_at":            "2012-04-02T22:55:29Z"
    },
    {
      ...
    }
  ]
}

Update Ticket Forms

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

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_forms/{id}.json \
  -H "Content-Type: application/json" -X PUT \
  -d '{ "ticket_form": {
          "name": "Snowboard Fixed",
          "display_name": "Snowboard has been fixed",
          "in_all_brands": true,
          "restricted_brand_ids": [],
          "agent_conditions": [],
          "end_user_conditions": []
      }}' \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK
Location: https://{subdomain}.zendesk.com/api/v2/ticket_forms/47.json

{
  "ticket_form": {
    "id":                    47,
    "url":                   "https://company.zendesk.com/api/v2/ticket_forms/47.json",
    "name":                  "Snowboard Fixed",
    "raw_name":              "Snowboard Fixed",
    "display_name":          "Snowboard has been fixed",
    "raw_display_name":      "Snowboard has been fixed",
    "end_user_visible":      true,
    "position":              9999,
    "active":                true,
    "default":               true,
    "in_all_brands":         true,
    "restricted_brand_ids":  [],
    "ticket_field_ids":      [ 2,4,5,32,44 ],
    "agent_conditions":      [],
    "end_user_conditions":   [],
    "created_at":            "2012-04-02T22:55:29Z",
    "updated_at":            "2012-04-02T22:55:29Z"
  }
}

Delete Ticket Form

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

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

Reorder Ticket Forms

PUT /api/v2/ticket_forms/reorder.json

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_forms/reorder.json \
  -H "Content-Type: application/json" -X PUT \
  -d '{"ticket_form_ids": [2, 23, 46, 50]}' \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "ticket_forms": [
    {
      "id":                    47,
      "url":                   "https://company.zendesk.com/api/v2/ticket_forms/47.json",
      "name":                  "Snowboard Fixed",
      "raw_name":              "Snowboard Fixed",
      "display_name":          "Snowboard has been fixed",
      "raw_display_name":      "Snowboard has been fixed",
      "end_user_visible":      true,
      "position":              9999,
      "active":                true,
      "default":               true,
      "in_all_brands":         true,
      "restricted_brand_ids":  [],
      "ticket_field_ids":      [ 2,4,5,32,44 ],
      "agent_conditions":      [],
      "end_user_conditions":   [],
      "created_at":            "2012-04-02T22:55:29Z",
      "updated_at":            "2012-04-02T22:55:29Z"
    }
  ]
}

Clone an already existing ticket form

POST /api/v2/ticket_forms/{id}/clone.json

Allowed For
  • Admins
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_forms/{id}/clone.json \
  -H "Content-Type: application/json" -X POST \
  -v -u {email_address}:{password} \
  -d { "prepend_clone_title": true }
Example Response
Status: 201 Created
Location: https://{subdomain}.zendesk.com/api/v2/ticket_forms/55.json

{
  "ticket_form": {
    "id":                    55,
    "url":                   "https://company.zendesk.com/api/v2/ticket_forms/55.json",
    "name":                  "Snowboard Fixed",
    "raw_name":              "Snowboard Fixed",
    "display_name":          "Snowboard has been fixed",
    "raw_display_name":      "Snowboard has been fixed",
    "end_user_visible":      true,
    "position":              9999,
    "active":                true,
    "default":               true,
    "in_all_brands":         false,
    "restricted_brand_ids":  [ 1,4,6,12,34 ]
    "ticket_field_ids":      [ 2,4,5,32,44 ]
    "agent_conditions":      [],
    "end_user_conditions":   [],
    "created_at":            "2012-04-02T22:55:29Z",
    "updated_at":            "2012-04-02T22:55:29Z"
  }
}