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
display_name string no no The name of the form that is displayed to an end user
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",
  "display_name":          "Snowboard Damage",
  "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",
      "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"
    }
  ]
}

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",
    "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 Field

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

Update Ticket Fields

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