Ticket Forms

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

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
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
in_all_organizations boolean no no Is the form available for use in all organizations on this account
restricted_organization_ids array yes no ids of all organizations that this ticket form is restricted to
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],
  "active":                      true,
  "default":                     true,
  "in_all_brands":               true
  "restricted_brand_ids":        []
  "in_all_organizations":        false
  "restricted_organization_ids": [ 47, 33, 22 ]
}

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 will only see the list of ticket forms that are marked 'end_user_visible'.

Allowed For
  • Anyone
Available Parameters

You can pass in any combination of the following optional filters:

Name Type Comment
active boolean Only active ticket forms if true, inactive ticket forms if false. Active and inactive ticket forms if not present.
end_user_visible boolean Only ticket forms marked 'end_user_visible' if true, ticket forms marked non 'end_user_visible' if false. End user and non end user visible if not present.
fallback_to_default boolean If true, returns 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 Only ticket forms of current brand (defined by url) if true.
Using curl
curl https://{subdomain}.zendesk.com/api/v2/ticket_forms.json \
  -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 ]
      "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": 2, "active" : true, "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":               true,
    "ticket_field_ids":      [ 2,4,5,32,44 ]
    "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 ]
    "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" }}' \
  -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":         false,
    "restricted_brand_ids":  [ 1,4,6,12,34 ]
    "ticket_field_ids":      [ 2,4,5,32,44 ]
    "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

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}
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 ]
    "created_at":            "2012-04-02T22:55:29Z",
    "updated_at":            "2012-04-02T22:55:29Z"
  }
}