Customers

How to list, create, 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
Content-Type: application/json; charset=utf-8

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
Content-Type: application/json; charset=utf-8

 {
     "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
Content-Type: application/json; charset=utf-8

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
Content-Type: application/json; charset=utf-8

 {
     "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
Content-Type: application/json; charset=utf-8

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
Content-Type: application/json; charset=utf-8

{
  "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
Content-Type: application/json; charset=utf-8

200 Response

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

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