API

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)
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

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

Example Response

Status: 204 No Content

Updating a ticket's priority

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

Parameters

Name Type Required Options Notes
priority string Yes "low", "medium", "high", "urgent" The name of the new ticket priority

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 Notes
group string Yes The ID or name of the group to assign the ticket to

Example Response

Status: 204 No Content