Add a follow-up

This method allows you to create a follow up on a ticket which will be executed at a later date.

URL

/api/v2/tickets/add_followup

Access

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

Supported Parameters

  • ticket - the reference of the ticket you wish to add a follow up to (required)
  • actor - the username or ID of the user who is actioning this follow up (required unless authenticating with a user token, in which case the follow up will always be associated with the token's user).

Specifying when the follow up should be executed

You can specify when the follow up should be executed in two ways:

  • You can send a run_at timestamp with the time in the format of yyyy-mm-dd hh:mm. The date you pass must be in the future. Formatting details can be found on the Date/Time Formatting page.
  • You can send a time_type parameter which should be minute, hour, day, week, month or year and time_length which must be an integer to represent a quantity of the length of time specified in the time_type parameter. For example, if you sent 'hour' and '2', your follow up would be added to run in 2 hours from now.

Specifying which actions should be executed

All of the options below are optional, you just need to pass those which you wish to change when the follow up is executed.

  • status - the name or ID of the status
  • priority - the name or ID of the priority, (send -1 to increase the priority, or -2 to decrease it)
  • team - the name or ID of the team (must be within the escalation path of the department) (send -1 to escalate the ticket, -2 to de-escalate it)
  • user - the username or ID of the assigned user (must be within the assigned team)
  • macro - the name or ID of a macro to execute
  • reply - the contents of a reply to post to the ticket
  • private_note - contents of a private note to post to the ticket

Returned Data

If the follow up is added successfully, you will receive a 201 Created response with details about the follow up you have just added. 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 follow-up

{
  "id": 17,
  "run_at": "2012-02-03T15:42:06+00:00",
  "actor": {
    "id": 1,
    "username": "adam",
    "first_name": "Adam",
    "last_name": "Cooke",
    "email_address": "adam@atechmedia.com",
    "time_zone": "London",
    "created_at": "2012-02-02T16:09:55+00:00"
  },
  "status": {
    "id": 1,
    "name": "New",
    "colour": "77c300",
    "status_type": 0
  },
  "priority": {
    "id": 1,
    "name": "Urgent",
    "colour": "f80000",
    "position": 1
  },
  "team": {
    "id": 2,
    "name": "1st Line Support"
  },
  "user": {
    "id": 1,
    "username": "adam",
    "first_name": "Adam",
    "last_name": "Cooke",
    "email_address": "adam@atechmedia.com",
    "time_zone": "London",
    "created_at": "2012-02-02T16:09:55+00:00"
  },
  "macro": {
    "id": 3,
    "name": "Resolve",
    "macro_type": "button"
  },
  "reply": "BLABHALBJ",
  "private_note": null
}

A failed follow-up

{
  "errors": {
    "run_at": [
      "must be greater than now"
    ]
  }
}