Documentation

Tickets

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

Request Overview

Actions

Returns

Description

GET /api/v1/tickets

Collection

Get all tickets

POST /api/v1/tickets

201 Object

Create ticket

GET /api/v1/tickets/{id}

200 Object

Get a ticket

PATCH /api/v1/tickets/{id}

200 Object

Update a ticket

DELETE /api/v1/tickets/{id}

200

Delete the ticket

Fields

Ticket Object

Field

Type

Specifics

id

Integer

subject

String

channel

Object

from_contact

Object

status

String

open escaleted waiting closed spam

assignee

Object

team

Object

creator

Object

tags

Array

last_contact

Date String

created_at

Date String

updated_at

Date String

deleted_at

Date String

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.

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": {
        "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=="
            }
        ]

    },
    "created_at": "2021-09-10 23:06:50"
}

201 Response

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

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

Field list

Field

Type

Required

Specifics

subject

String

Yes

channel

Object

Yes

from_contact

Object

Yes

You can provide email and name. Name is only used if the contact is not existing. By default, the name is converted from the email.

status

String

No

open escaleted waiting closed spam

assignee

Object

No

team

Object

No

tags

Array

No

Provide all tag names in an array. Only existing tags of type all or ticket will be applied.

message

Object

Yes

message.body

String

Yes

The body can contain inline images with a base64 DataURL.

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

Max body size is 5 MB.

message.attachments

Array

No

All attachments together can consume 5 MB

created_at

Date String

No

skip_rules

Boolean

No

Skip rules checks for this ticket

skip_autoreply

Boolean

No

Do not send autoreply message to from_contact

skip_notifications

Boolean

No

Do not send notifications to agents.

Attachment object

Field

Type

Required

Specifics

name

String

Yes

mime_type

String

Yes

data

String

Yes

base64 image PHN2ZyB3==

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

Field

Type

Nullable

Specifics

subject

String

No

channel

Object

No

You can provide id or email

from_contact

Object

No

You can provide email and name. Name is only used if the contact is not existing. By default, the name is converted from the email.

status

String

No

open escaleted waiting closed spam

assignee

Object

Yes

You can provide id or email

team

String

max:14

Yes

You can provide id or name

tags

Array

No

Provide all tag names in an array. All existing tags will be removed. Only existing tags of type all or ticket will be applied. To remove all tags, provide an empty array.

created_at

String

No

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."
}