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

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,
}

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

  • Admins, Agents, End Users

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,
      "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,
    "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,
    "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: 200 OK

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,
    "ticket_field_ids":      [ 2,4,5,32,44 ]
    "created_at":            "2012-04-02T22:55:29Z",
    "updated_at":            "2012-04-02T22:55:29Z"
  }
}

comments powered by Disqus