Tickets

How to list, create, get, update and delete tickets

Request Overview

Fields

Ticket Object

Requests

Get All Tickets

GET /api/v1/tickets Returns, a collection of tickets

GET /api/v1/tickets HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com
Content-Type: application/json; charset=utf-8

200 Response

HTTP/1.1 200 OK
Content-Type: application/json
...

{
  "data": [
    {
       "id": 5465,
       "subject": "Ticket name",
       ...
    },
    {
       "id": 5466,
       "subject": "Ticket name",
       ...
    },
    ...
  ],
  "links": {
    ...
  },
  "meta": {
    ...
  }
}

Information about links and meta please read this article.

Filter with query parameters

To filter results, you can add query parameters to the request URL.
For example: /api/v1/tickets?assignees[]=mike%20smith&status[]=open

Example-Queries

Invoices from Customer

In the request below, we want to get open tickets from @example.com that contain the word invoice in the subject or body.

/api/v1/tickets/?per-page=50&subject-or-body[]=invoice&contact[]=%40example.com&status[]=open

Tickets with tags

To request all tickets that have the tag bug and also the tag ui

/api/v1/tickets/?tags[]=bug&tags[]=ui

Create Ticket

POST /api/v1/tickets Creates a new ticket

POST /api/v1/tickets HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com
Content-Type: application/json; charset=utf-8

{   
    "subject": "Name of a new ticket",
    "from_contact": {
        "email": "some.name@customer.de"
    },
    "channel": {
      "id": 1
    },
    "team": {
      "name": "Billing"
    },
    "assignee": {
        "id": 1
    },
    "status": 1,
    "message": {
        "from_contact": {
            "email": "some.name@example.com",
            "name": "Some Name"
        },
        "body": "<p>Hi. Here is a image. 
                 <img alt=\"screen.png\" src=\"data:image\/png;base64,PHN2ZyB3==",
        "attachments": [
            {
                "name": "some.pdf",
                "mime_type": "application/pdf",
                "data" : "iVBORw0KGgo=="
            },
            {
                "name": "another.jpg",
                "mime_type": "image/jpeg",
                "data" : "PHN2ZyB3=="
            }
        ]

    },
    "send_mail_to_recipients": true,
}

201 Response

HTTP/1.1 201 OK
Content-Type: application/json
...

{
  "data": {
    // Object like in get customer request
  }
}

Field list

<img src="data:image/png;base64,iVBORw0KG==" alt="Some Name" />

Attachment object

Get Ticket

GET /api/v1/tickets/{id} Returns the ticket object

GET /api/v1/tickets/{{id}} HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com
Content-Type: application/json; charset=utf-8

200 Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Encoding: gzip
...

{
  "data": {
    "id": 2517,
    "subject": "New Ticket name",
    "channel": {
      "id": 1,
      "name": "Support",
      "value": "support@your-domain.com",
      "type": "email"
    },
    "from_contact": {
      "id": 1008,
      "user_id":950,
      "name": "Sam Smith",
      "value": "sam@smith.com",
      "type": "email"
    },
    "status": "closed",
    "assignee": {
      "id": 3,
      "name": "Joe",
      "email": "joe@your-domain.com"
    },
    "team": null,
    "creator": {
      "id": 3,
      "name": "Main Account",
      "email": "support@your-domain.com"
    },
    "tags": [],
    "last_contact": "2022-02-04T13:36:55+00:00",
    "created_at": "2021-09-10T23:06:50+00:00",
    "updated_at": "2022-02-04T13:37:04+00:00",
    "deleted_at": null
  }
}

Update Ticket

PATCH /api/v1/tickets/{id} Returns the ticket object

PATCH /api/v1/tickets/{{id}} HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com
Content-Type: application/json; charset=utf-8

 {
    "subject": "New Ticket name",
    "channel": {
        "id": 1
    },
    "status": "closed",
    "assignee": {
        "id": 3
    },
    "team": {
        "name": "Support"
    },
    "from_contact": {
        "name": "Mike Someone",
        "email": "appppppp@ccom.no"
    },
    "tags": ["Bug", "Spam"],
    "created_at": "2021-09-10T23:06:50+00:00"
}

200 Response

HTTP/1.1 200 OK
Content-Type: application/json
...

{
  "data": {
    // Object like in get customer request
  }
}

Field list

Delete Ticket

DELETE /api/v1/tickets/{id} Soft deletes an existing ticket.

Tickets will be deleted permanently 30 days later.

DELETE /api/v1/tickets/{{id}} HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com
Content-Type: application/json; charset=utf-8

200 Response

HTTP/1.1 200 OK

{
  "message": "Object deleted."
}