Documentation

Customers

How to list, get, update and delete customers

Request Overview

Actions

Returns

Description

GET /api/v1/customers

Collection

Get all customers

POST /api/v1/customers

201 Object

Create customer

GET /api/v1/customers/{id}

200 Object

Get a customer

PATCH /api/v1/customers/{id}

200 Object

Update a customer

DELETE /api/v1/customers/{id}

200

Delete the customer and all tickets of the customer permanently. It's not possible to restore the data.

GET /api/v1/customers/{id}/avatar

200 Object

Get customer avatar

PATCH /api/v1/customers/{id}/avatar

200 Object

Update customer avatar

Fields

Customer Object

Field

Type

Required

Specifics

name

String

yes

email

String

yes

Must be a valid email.

job_title

String

-

address

String

-

city

String

-

state

String

-

postal_code

String

max:14

-

timezone

String

Timezone

-

Must be a valid timezone of the PHP function timezoneidentifierslist

country

String

-

note

String

max:1500

Sanitized HTML

-

HTML will be sanitized.

locale

String

-

Locale like en-US,

de-DE ...

Unsupported Locales will be dropped.

created_at

String

-

Avatar Object

Field

Type

Required

mime_type

String

image/jpeg image/png image/gif image/bmp

yes

data

Base64 Image

max:50000

yes

Requests

Get All Customers

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

GET /api/v1/customers HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com

200 Response

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

{
  "data": [
    {
      "id": 1,
      "id_link": "https:\/\/api.helpspace.com\/api\/v1\/customer\/1",
      "name":  "New Customer",
      "email": "some@email.de",
      "job_title": "Master of ...",
      "address": "Some Address",
      "city": "Boston",
      "state": "Massachusetts",
      "postal_code": "02135",
      "timezone": "America/New_York",
      "country": "America",
      "note": "Some Text",
      "locale": "en-US"
      "created_at": "2021-09-03T12:40:43+00:00",
      "updated_at": "2021-09-03T12:40:43+00:00"
    },
    ...
  ],
  "links": {
    ...
  },
  "meta": {
    ...
  }
}
Information about links and meta please read this article.

Create Customer

POST /api/v1/customers Creates a new customer

POST /api/v1/customers HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com

 {
     "name":  "New Customer",
     "email": "some@email.com",
     "job_title": "Master of ...",
     "address": "Some Address",
     "city": "Boston",
     "state": "Massachusetts",
     "postal_code": "02135",
     "timezone": "America/New_York",
     "country": "America",
     "note": "Some Text",
     "locale": "en-US"
 }

201 Response

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

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

Get Customer

GET /api/v1/customers/{id} Returns the customer object

GET /api/v1/customers/{{id}} HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com

200 Response

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

{
  "data": {
    "id": 99,
    "name":  "New Customer",
    "email": "some@email.de",
    "job_title": "Master of ...",
    "address": "Some Address",
    "city": "Boston",
    "state": "Massachusetts",
    "postal_code": "02135",
    "timezone": "America/New_York",
    "country": "America",
    "note": "Some Text",
    "locale": "en-US"
    "created_at": "2021-09-03T12:40:43+00:00",
    "updated_at": "2021-09-03T12:40:43+00:00"
  }
}

Update Customer

PATCH /api/v1/customers/{id} Returns the customer object

PATCH /api/v1/customers/{{id}} HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com

 {
     "name":  "New Customer",
     "email": "some@email.com",
     "job_title": "Master of ...",
     "address": "Some Address",
     "city": "Boston",
     "state": "Massachusetts",
     "postal_code": "02135",
     "timezone": "America/New_York",
     "country": "America",
     "note": "Some Text",
     "locale": "en-US",
     "created_at": "2021-09-03 12:40:43+00:00"
 }

200 Response

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

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

Delete Customer

DELETE /api/v1/customers/{id} Deletes an existing customer and all its tickets permanently!!!

Be careful with deleting customers.
For data protection perpose, all tickets of the customer will be deleted permanently too.

DELETE /api/v1/customers/{{id}} HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com

200 Response

HTTP/1.1 200 OK

{
  "message": "Object deleted permanently."
}

Update Avatar

PATCH /api/v1/customers/{id}/avatar Returns the updated avatar object

POST /api/v1/customers/{{id}}/avatar HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com

{
  "mime_type": "image/gif",
  "data" : "R0lGODlh=="
}

200 Response

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

{
  "data": {
    "mime_type": "image/gif",
    "data" : "R0lGODlh=="
  }
}

Get Avatar

GET /api/v1/customers/{id}/avatar Returns the updated avatar object

POST /api/v1/customers/{{id}}/avatar HTTP/1.1
Authorization: Bearer {{token}}
Hs-Client-Id: {{hs_client_id}}
Host: api.helpspace.com

200 Response

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

{
  "data": {
    "mime_type": "image/gif",
    "data" : "R0lGODlh=="
  }
}