Organizations

How to list, create, update and delete organizations

Request Overview

Action	Returns	Description
`GET /api/v1/organizations`	Collection	Get all organizations
`GET /api/v1/organizations/{id}`	Object	Get a single organization
`POST /api/v1/organizations`	Object	Create organization
`PATCH /api/v1/organizations/{id}`	Object	Update organization
`DELETE /api/v1/organizations/{id}`		Delete organization

Fields

Field	Type	Required	Specifics
name	`String`	yes	Must be unique
domain	`String`		Must be a valid domain and unique.
note	`String`
custom_fields	`Object`		Key/value pairs of custom fields.
avatar	`String`		Read-only. Auto-generated favicon URL based on the domain or name.
timezone	`String`		Must be a valid timezone identifier (e.g. `Europe/Berlin`).
locale	`String`		Must be a valid, enabled locale (e.g. `en-US`).
is_shared	`Boolean`
is_domain_assignable	`Boolean`		Whether contacts with a matching email domain are auto-assigned.
tags	`Array`		Array of tag IDs (organization tags) to sync with the organization.
users	`Array`		Read-only. Contacts that belong to the organization.
created_at	`Date String`
updated_at	`Date String`

Requests

Get All Organizations

GET /api/v1/organizations Returns a collection of organizations

GET /api/v1/organizations 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,
      "name": "Acme Corp",
      "domain": "acme.com",
      "note": "Key account since 2021",
      "custom_fields": [],
      "avatar": "https://favapi.helpspace.com/favicon/image?url=acme.com",
      "timezone": "Europe/Berlin",
      "locale": "en-US",
      "is_shared": true,
      "is_domain_assignable": true,
      "users": [
        {
          "id": 42,
          "name": "Jane Doe",
          "email": "jane@acme.com",
          "is_agent": false
        }
      ],
      "tags": [
        {
          "id": 3,
          "name": "VIP",
          "slug": "vip",
          "color": "#1477EA",
          "type": "organization"
        }
      ],
      "created_at": "2023-05-31T14:12:10+00:00",
      "updated_at": "2024-07-18T13:28:52+00:00"
    }
  ],
  "links": {
    "..."
  },
  "meta": {
    "..."
  }
}

Information about links and meta, please read this article.

Get Organization

GET /api/v1/organizations/{id} Returns a single organization

GET /api/v1/organizations/1 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,
    "name": "Acme Corp",
    "domain": "acme.com",
    "note": "Key account since 2021",
    "custom_fields": [],
    "avatar": "https://favapi.helpspace.com/favicon/image?url=acme.com",
    "timezone": "Europe/Berlin",
    "locale": "en-US",
    "is_shared": true,
    "is_domain_assignable": true,
    "users": [],
    "tags": [],
    "created_at": "2023-05-31T14:12:10+00:00",
    "updated_at": "2024-07-18T13:28:52+00:00"
  }
}

Create Organization

POST /api/v1/organizations Create an organization

POST /api/v1/organizations 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 Organization",
  "domain": "new-organization.com",
  "note": "Optional note",
  "timezone": "Europe/Berlin",
  "locale": "en-US",
  "is_shared": true,
  "is_domain_assignable": false,
  "tags": [3]
}

200 Response

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

{
  "data": {
    "id": 2,
    "name": "New Organization",
    "domain": "new-organization.com",
    "note": "Optional note",
    "custom_fields": [],
    "avatar": "https://favapi.helpspace.com/favicon/image?url=new-organization.com",
    "timezone": "Europe/Berlin",
    "locale": "en-US",
    "is_shared": true,
    "is_domain_assignable": false,
    "users": [],
    "tags": [
      {
        "id": 3,
        "name": "VIP",
        "slug": "vip",
        "color": "#1477EA",
        "type": "organization"
      }
    ],
    "created_at": "2024-07-18T13:28:52+00:00",
    "updated_at": "2024-07-18T13:28:52+00:00"
  }
}

Update Organization

PATCH /api/v1/organizations/{id} Update an organization

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

{
  "name": "Updated Organization name",
  "note": "Updated note"
}

200 Response

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

{
  "data": {
    "id": 2,
    "name": "Updated Organization name",
    "domain": "new-organization.com",
    "note": "Updated note",
    "custom_fields": [],
    "avatar": "https://favapi.helpspace.com/favicon/image?url=new-organization.com",
    "timezone": "Europe/Berlin",
    "locale": "en-US",
    "is_shared": true,
    "is_domain_assignable": false,
    "users": [],
    "tags": [],
    "created_at": "2024-07-18T13:28:52+00:00",
    "updated_at": "2024-07-18T13:35:04+00:00"
  }
}

Delete Organization

DELETE /api/v1/organizations/{id} Delete an organization

DELETE /api/v1/organizations/2 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

{
  "message": "Object deleted permanently"
}