This method allows you to submit a new ticket into the support site. It should be noted however, this will not add any content to a ticket and this must be added with a separate call to the 'Posting an update' method.

URL

/api/v2/tickets/submit

Access

This method can be accessed by account tokens and user tokens where the associated user has access to the tickets UI.

Supported Parameters

There are a number of parameters which are supported for submitting a ticket. References to other objects can be passed by sending it's ID or by passing its name (case insensitive).

• subject - the subject for the ticket (required)
• status - the name or ID of a status (required)
• priority - the name or ID of a priority (required)
• sla - the name or ID of a SLA
• brand - the name or ID of a brand
• department - the name or ID of a department (the name is only permitted when a brand is passed too, otherwise an ID is required).
• team - the name or ID of a team (required and must be within the escalation path for the department)
• user - the username or ID of an assigned user (optional but must be assigned to the chosen team)
• tag_list - a space or comma separated list of tags for this ticket
• submitted_at - the date/time the ticket was created (optional, leave blank for now). Formatting details can be found on the Date/Time Formatting page.

Passing custom fields

• custom[fieldname] - a hash of custom field values where fieldname is the system name of the custom field you wish to save.

Passing the contact information

When submitting a ticket you can link a ticket a contact which already exists or one can be created as part of this process. The following parameters are required:

• contact_method_type - the type of contact method to use (email or telephone)
• contact_method_data - the contact method (email address or telephone number) which should be looked up
• contact_name - the name of the contact

If when processing these fields we find an existing contact with the provided contact method, this will be used and the value submitted as contact_name will not be used and the current name will apply. If no contact is found, one will be created using the name & contact method provided.

Alternatively, if you know the ID of an existing contact & contact method you can pass the contact and contact_method parameters which should include the numerical IDs for the contact & contact method you wish to use.

Bear in mind that if your contact has an SLA or priority override set, any values you set as sla or priority will be ignored if the preference of that is set for the contact.

Including additional contacts

Tickets can have multiple contact methods associated with them. Whenever an update is posted to a ticket, messages will be sent them too. to set these you can use the additional_contact_methods parameter. If you use this, you must provide all contact methods which you wish to be present on the ticket. Multiple methods should be separated by commas. For example; adam@atech.io,dave@atech.io,steve@atech.io.

Providing an initial ticket update

If you wish to also provide an initial update with your new ticket, you can pass a message parameter containing the update content. The author will be automatically added based on the contact that you set in the main ticket hash.

Returned data

If the ticket is created successfully, a 201 Created response will be returned along with the ticket data as shown on the ticket properties page. If a validation error occurs, you will receive a 422 Unprocessable Entity status along with an array of errors (see below)

Example JSON

A successful ticket submission

{
  "id": 33,
  "reference": "FC-408862",
  "subject": "Example API Ticket",
  "message_id": "a059140a-e4a3-6d1c-d8ba-3ae0124a55ba@sirportly.dev",
  "submitted_at": "2012-02-03T12:00:36+00:00",
  "reply_due_at": "2012-02-03T12:30:35+00:00",
  "resolution_due_at": null,
  "auth_code": "l7qih9667paf",
  "additional_recipients": null,
  "last_update_posted_at": null,
  "first_response_time": null,
  "first_resolution_time": null,
  "resolution_time": null,
  "last_respondant": null,
  "update_count": 0,
  "status": {
    "id": 1,
    "name": "New",
    "colour": "77c300",
    "status_type": 0
  },
  "priority": {
    "id": 3,
    "name": "Normal",
    "colour": "0097cf",
    "position": 3
  },
  "department": {
    "id": 3,
    "name": "Technical Support",
    "brand": {
      "id": 2,
      "name": "Codebase",
      "url": "http://www.codebasehq.com"
    },
    "escalation_path": {
      "id": 2,
      "name": "aTech Technical Support Path"
    },
    "private": false
  },
  "team": {
    "id": 2,
    "name": "1st Line Support"
  },
  "user": {
    "id": 2,
    "username": "charlie",
    "first_name": "Charlie",
    "last_name": "Smurthwaite",
    "email_address": "charlie@atechmedia.com",
    "time_zone": "UTC",
    "created_at": "2012-02-02T16:09:55+00:00"
  },
  "sla": {
    "id": 1,
    "name": "Standard Response",
    "reply_in": 30,
    "resolution_in": null
  },
  "contact": {
    "id": 1,
    "name": "Adam Cooke",
    "company": "aTech Media",
    "pin": "484836"
  },
  "contactcontact_method": {
    "id": 1,
    "method_type": "email",
    "data": "adam@atechmedia.com"
  }
}

A failed ticket submission

{
  "errors": {
    "department_id": [
      "can't be blank"
    ],
    "priority_id": [
      "can't be blank"
    ],
    "status_id": [
      "can't be blank"
    ],
    "contact_id": [
      "can't be blank"
    ],
    "contact_method_id": [
      "can't be blank"
    ],
    "team_id": [
      "can't be blank"
    ],
    "reference": [
      "can't be blank"
    ],
    "subject": [
      "can't be blank"
    ]
  }
}