Support Hub API

# Categories

Manage system categories. Available for administrators only.

# Category Object

Name Type Comment
id integer Unique category identifier.
name string A category name.
order integer Category order to be used for sorting categories.
thumbnail string A category thumbnail URL
envato_item_id integer An ID for the Envato item object or null if there is no Envato item associated.
purchase_verification integer Purchase verification requirements.
created_at datetime Category creation timestamp.
updated_at datetime Category update timestamp.

A purchase_verification attribute can have the following values:

Purchase Verification Value
Not Required 0
Valid Code 1
Valid Code and Support 2

# Envato Item Object

Name Type Comment
id integer Unique item identifier.
envato_id integer Item's ID on Envato marketplace.
marketplace string The name of the Envato marketplace (eg. codecanyon)
name string Item name.
url string An URL of the item on Envato marketplace.
thumbnail string A thumbnail URL
created_at datetime Category creation timestamp.
updated_at datetime Category update timestamp.

# Paginate Categories

GET
/categories

# Request

curl --location --request GET 'https://yoursubdomain.support-hub.io/api/categories' \
--header 'Accept: aplication/json'

# Example Response

{
    "data": [
       {
          "id": 11,
          "name": "Vanguard - Advanced PHP Login and User Management",
          "order": 2,
          "thumbnail": "https://s3.envato.com/files/167924441/80x80-Vanguard.png",
          "envato_item_id": 9,
          "purchase_verification": 2,
          "created_at": "2018-11-13 16:29:31",
          "updated_at": "2019-07-09 14:41:40"
        },
      //...
    ],
    "links": {
        //...
    },
    "meta": {
        //...
    }
}

# Available includes

If provided, the available includes will be part of the response for each category object.

agents-count

Number of agents associated to the category.

tickets-count

Number of tickets within the category.

articles-count

Number of articles within the given category.

article-collections-count

Number of article collections within the given category.

custom-fields

A list of custom fields object for the category.

envato-item

An envato item object associated with the category.

# Sortable Fields

name, order (default), created_at

# Partial filters

name

# View a Category

GET
/categories/{id}

# Request

curl --location --request GET 'https://yoursubdomain.support-hub.io/api/categories/{id}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

# Example Response

{
    "data": {
      "id": 11,
      "name": "Vanguard - Advanced PHP Login and User Management",
      "order": 2,
      "thumbnail": "https://s3.envato.com/files/167924441/80x80-Vanguard.png",
      "envato_item_id": 9,
      "purchase_verification": 2,
      "created_at": "2018-11-13 16:29:31",
      "updated_at": "2019-07-09 14:41:40"
    }
}

# Available includes

Same as when paginating the categories.

# Create a Category

POST
/categories
Parameter Type Required Validation
name string yes Unique string up to 250 characters long.

# Request

curl --location --request POST 'https://yoursubdomain.support-hub.io/api/categories' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Random Category"
}'

# Example Response

Status: 201 Created

{
    "data": {
      "id": 12,
      "name": "Random Category",
      "order": 1,
      "thumbnail": null,
      "envato_item_id": null,
      "purchase_verification": 0,
      "created_at": "2019-07-09 14:41:40",
      "updated_at": "2019-07-09 14:41:40"
    }
}

# Update a Category

PATCH
/categories/{id}
Parameter Type Required Validation
name string no Unique string up to 250 characters long.
envato_item_id integer no Valid Envato Item ID.

# Request

curl --location --request PATCH 'https://yoursubdomain.support-hub.io/api/categories/{id}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Updated Category"
}'

# Example Response

Status: 200 OK

{
    "data": {
      "id": 12,
      "name": "Updated Category",
      "order": 1,
      "thumbnail": null,
      "envato_item_id": null,
      "purchase_verification": 0,
      "created_at": "2019-07-09 14:41:40",
      "updated_at": "2019-07-09 14:41:40"
    }
}

# Delete a Category

DELETE
/categories/{id}

# Request

curl --location --request DELETE 'https://yoursubdomain.support-hub.io/api/categories/{id}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "Updated Category"
}'

# Example Response

Status: 200 OK

{
    "success": true
}

# Update Categories Order

POST
/categories/order
Parameter Type Required Validation Example
order array yes An associative array of order => category_id elements. [0 => 1100, 1 => 1344, 2 => 3211]

TIP

If you want you can omit the index inside the associative array and and the order property will be updated according to the position of the order_id within the received order array.

# Request

curl --location --request POST 'https://yoursubdomain.support-hub.io/api/categories/order' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "order": [
    1100,
    1344,
    3211
  ]
}'

# Example Response

Status: 200 OK

{
    "success": true
}

# Paginate Assigned Agents

Paginate agents assigned to the category.

GET
/categories/{id}/agents

# Request

curl --location --request GET 'https://yoursubdomain.support-hub.io/api/categories/{id}/agents' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

# Example Response

Same as when paginating the agents.

# Available includes

Same as when paginating the agents.

# Partial filters

first_name, last_name

# Assign Agents

Assign provided agents to the category.

POST
/categories/{id}/agents
Parameter Type Required Validation
agents array yes A list of agent IDs to be assigned to the category

WARNING

Only provided agents will be assigned to this category and all other will be removed.

# Request

curl --location --request POST 'https://yoursubdomain.support-hub.io/api/categories/{id}/agents' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "agents": [
    123,
    456
  ]
}'

# Example Response

Status: 200 OK

{
  "success": true
}

# Remove Assigned Agents

DELETE
/categories/{id}/agents
Parameter Type Required Validation
agents array yes A list of agent IDs to remove from the category.

# Request

curl --location --request DELETE 'https://yoursubdomain.support-hub.io/api/categories/{id}/agents' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "agents": [
    123
  ]
}'

# Example Response

Status: 200 OK

{
  "success": true
}

# Paginate Article Collections

GET
/categories/{id}/collections

# Request

curl --location --request GET 'https://yoursubdomain.support-hub.io/api/categories/{id}/collections' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

# Example Response

Same as when paginating the collections.

# Available includes

Same as when paginating the collections.

# Partial filters

name

# Upload Thumbnail

POST
/categories/{id}/thumbnail

# Parameters

Parameter Type Required Validation
image file yes A valid image file with the following extensions: jpg, png.
points[x1] number Only when other cropping points are provided.
points[x2] number Only when other cropping points are provided.
points[y1] number Only when other cropping points are provided.
points[y2] number Only when other cropping points are provided.

# Request

curl --location --request POST 'https://yoursubdomain.support-hub.io/api/categories/{id}/thumbnail' \
--header 'Accept: application/json' \
--header 'Content-Type: multipart/form-data' \
--form 'image=testimage.png' \
--form 'points[x1]=0' \
--form 'points[x2]=0' \
--form 'points[y1]=100'

# Example Response

Same as when viewing a category.

# Update Thumbnail From Envato

Updates thumbnail from associated Envato item, if applicable.

POST
/categories/{id}/thumbnail/envato

# Request

curl --location --request POST 'https://yoursubdomain.support-hub.io/api/categories/{id}/thumbnail/envato' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

# Example Response

Same as when viewing a category.

# Remove Thumbnail

Removes the thumbnail image for the category.

DELETE
/categories/{id}/thumbnail

# Request

curl --location --request DELETE 'https://yoursubdomain.support-hub.io/api/categories/{id}/thumbnail' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

# Example Response

Status: 200 OK

{
  "success": true
}

# Get Custom Fields

Get all custom fields associated with a category.

GET
/categories/{id}/fields

# Request

curl --location --request GET 'https://yoursubdomain.support-hub.io/api/categories/{id}/fields' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

# Example Response

Status: 200 OK

{
  "data": [
      {
        "id": 4,
        "type": "text",
        "title": "Foo",
        "placeholder": null,
        "description": null,
        "required": false,
        "meta": [],
        "created_at": "2019-09-25 11:54:22",
        "updated_at": "2019-09-25 11:54:22"
      },
      //...
  ]
}

# Partial filters

title

# Sync Custom Fields

Synchronize custom fields associated with this category.

POST
/categories/{id}/fields

WARNING

Only custom fields provided within this request will remain associated with the category.

TIP

The order in which those custom fields are provided within the request will also be the order in which they will always be returned back from the server.

# Parameters

Parameter Type Required Validation
fields array yes A list of custom field IDs to be associated with the category.

# Request

curl --location --request POST 'https://yoursubdomain.support-hub.io/api/categories/{id}/fields' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "fields": [
    123,
    456
  ]
}'

# Example Response

Status: 200 OK

{
  "success": true 
}

← Article Collections →