Tickets

Creating a new ticket

POST https://api.groovehq.com/v1/tickets

Parameters

Name	Type	Required	Default	Notes
body	string	Yes		The body of the first comment to add to the ticket
from	string or hash	Yes		The email address of the agent or customer who sent the ticket or hash of customer attributes (defined below)
to	string or hash	Yes		The email address of the customer or mailbox that the ticket is addressed to or a hash of customer attributes (defined below)
mailbox	string	No		The email or ID of the mailbox the ticket should be created in. If omitted, defaults to the primary mailbox.
assigned_group	string	No		The name of the assigned group
assignee	string	No		The email of the agent to assign the ticket to
sent_at	datetime	No		Can be used to set the created and updated datetimes to sometime in the past. RFC-822 format preferred
note	boolean	No	false	When creating a ticket from an agent, should the message body be added as a private note
send_copy_to_customer	boolean	No	false	When creating a ticket from an agent, should the message be emailed to the customer
state	string	No	unread	The ticket state. Allowed states are: "unread", "opened", "pending", "closed", "spam"
subject	string	No		The email subject of your ticket
tags	array	No		A list of tag names
starred	boolean	No	false	Should the ticket be starred
skip_notifications	boolean	No	false	Skip all agent notifications.

Optional Customer Parameters

Name	Type	Required	Notes
email	string	Yes	The customer's email
name	string	No	The customer's name
about	string	No	Some text about the customer
twitter_username	string	No	The customer's twitter user name
title	string	No	The customer's title
company_name	string	No	The customer's company name
phone_number	string	No	The customer's phone number
location	string	No	The customer's location
linkedin_username	string	No	The customer's linkedin username

Example Response

Status: 201 Created
Location: https://api.groovehq.com/v1/tickets/:ticket_number

{
    "ticket": {
        "number": 1,
        "href": "https://api.groovehq.com/v1/tickets/1",
        "links": {
            "assignee": {
                "href": "https://api.groovehq.com/v1/agents/matt@groovehq.com"
            },
            "customer": {
                "href": "https://api.groovehq.com/v1/customers/customer@somewhere.com"
            },
            "state": {
                "href": "https://api.groovehq.com/v1/tickets/1/state"
            },
            "messages": {
                "href": "https://api.groovehq.com/v1/tickets/1/messages"
            }
        }
    }
}

Listing tickets

GET https://api.groovehq.com/v1/tickets

Parameters

Name	Type	Required	Default	Options	Notes
assignee	string	No		agent email or "unassigned"	The email address of the assignee or "unassigned" to find all unassigned tickets
customer	string	No		customer email or ID	Returns tickets belonging to the specified customer
page	integer	No	1		The page number
per_page	integer	No	25		The number of messages to return per page (max 50)
state	string	No		"unread", "opened", "pending", "closed", "spam"	Returns tickets with the specified state only
folder	integer	No			The ID of a folder to filter by

Example Response

Status: 200 OK

{
    "tickets": [{
        "assigned_group": null,
        "created_at": "2012-07-17T13:41:01Z",
        "number": 1,
        "priority": null,
        "resolution_time": null,
        "title": null,
        "updated_at": "2012-07-17T13:41:01Z",
        "href": "https://api.groovehq.com/v1/tickets/1",
        "closed_by": null,
        "tags": ["important"],
        "message_count": 1,
        "summary": "This is the first 100 characters of the first message...",
        "links": {
            "assignee": {
                "href": "https://api.groovehq.com/v1/agents/matt@groovehq.com"
            },
            "customer": {
                "href": "https://api.groovehq.com/v1/customers/customer@somewhere.com"
            },
            "state": {
                "href": "https://api.groovehq.com/v1/tickets/1/state"
            },
            "messages": {
                "href": "https://api.groovehq.com/v1/tickets/1/messages"
            }
        }
    }],
    "meta": {
        "pagination": {
            "current_page": 1,
            "total_pages": 23,
            "total_count": 23,
            "next_page": "http://api.groovehq.dev/v1/tickets?page=2"
        }
    }
}

Finding one ticket

GET https://api.groovehq.com/v1/tickets/:ticket_number

Example Response

Status: 200 OK

{
    "ticket": {
        "assigned_group": null,
        "created_at": "2012-07-17T13:41:01Z",
        "number": 1,
        "priority": null,
        "resolution_time": null,
        "title": null,
        "updated_at":"2012-07-17T13:41:01Z",
        "href": "https://api.groovehq.com/v1/tickets/1",
        "closed_by": "matt@groovehq.com",
        "tags": ["important"],
        "message_count": 1,
        "starred": false,
        "summary": "This is the first 100 characters of the first message...",
        "links": {
            "assignee": {
                "href": "https://api.groovehq.com/v1/agents/matt@groovehq.com"
            },
            "customer": {
                "href": "https://api.groovehq.com/v1/customers/customer@somewhere.com"
            },
            "state": {
                "href": "https://api.groovehq.com/v1/tickets/1/state"
            },
            "messages": {
                "href": "https://api.groovehq.com/v1/tickets/1/messages"
            }
        }
    }
}

Finding a ticket’s state

GET https://api.groovehq.com/v1/tickets/:ticket_number/state

Example Response

Status: 200 OK

{
    "state": "unread"
}

Updating a ticket state

PUT https://api.groovehq.com/v1/tickets/:ticket_number/state

Parameters

Name	Type	Required	Default	Options	Notes
state	string	Yes		"unread", "opened", "pending", "closed","spam"	The new ticket state

Example Response

Status: 204 No Content

Finding a ticket’s assignee

GET https://api.groovehq.com/v1/tickets/:ticket_number/assignee

Example Response

Status: 200 OK

{
  "agent": {
    "email": "matt@groovehq.com",
    "first_name": "Matthew",
    "last_name": "Beedle",
    "href": "https://api.groovehq.com/v1/agents/matt@groovehq.com",
    "links": {
      "tickets": {
        "href": "https://api.groovehq.com/v1/tickets?assignee=matt%40groovehq.com"
      }
    }
  }
}

Updating a ticket assignee

PUT https://api.groovehq.com/v1/tickets/:ticket_number/assignee

Parameters

Name	Type	Required	Default	Options	Notes
assignee	string	Yes			The email of the agent to assign the ticket to
skip_notifications	boolean	No	false		Skip sending reassignment notifications to agents

Example Response

Status: 204 No Content

Updating a ticket's assigned group

PUT https://api.groovehq.com/v1/tickets/:ticket_number/assigned_group

Parameters

Name	Type	Required	Default	Options	Notes
group	string	Yes			The ID or name of the group to assign the ticket to
skip_notifications	boolean	No	false		Skip sending reassignment notifications to agents

Example Response

Status: 204 No Content

Add labels to a ticket

POST https://api.groovehq.com/v1/tickets/:ticket_number/tags

Parameters

Name	Type	Required	Default	Options	Notes
tags	array	Yes		["your", "new", "labels"]	The labels to add to the ticket

Example Response

Status: 201 Created

{
    "ticket": {
        "created_at": "2017-12-13T05:50:42Z",
        "href": "https://api.groovehq.com/v1/tickets/1234",
        "links": {
           ...
        }
        "number": 1234,
        "priority": "low",
        "state": "opened",
        ...
        "tags": [
            "some",
            "new",
            "labels"
        ],
        "tag_ids": [
            1986,
            1987,
            1989
        ],
        ...
    }
}

Replacing all labels on a ticket

PUT https://api.groovehq.com/v1/tickets/:ticket_number/tags

Parameters

Name	Type	Required	Default	Options	Notes
tags	array	Yes		["your", "replacement", "labels"]	The new set of labels for the ticket (replaces all existing!)

Example Response

Status: 204 No Content

Change Mailbox

POST https://api.groovehq.com/v1/tickets/:ticket_id/change_mailbox/:mailbox_id

Example Response

Status: 204 No Content
Location: https://api.groovehq.com/v1/tickets/1/change_mailbox/10