Introduction

The Support Hub API is a REST API that covers all endpoints that you can use to communicate with your Support Hub account and without logging in to the Support Hub web application.

HTTP Status Codes

HTTP Status Code	Status Message	Description
200	OK	Everything worked as expected.
201	Created	Resource was created successfully.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid API key provided.
403	Forbidden	Accessing the resource is forbidden for this user.
404	Not Found	The requested resource doesn't exist.
422	Unprocessable Entity	Required fields are missing or cannot be processed.
500, 502, 503, 504	Server Errors	Something went wrong on Support Hub's end.

Rate Limit

The number of API calls per minute are based on the subscription plan you are currently subscribed on.

Subscription Plan	Requests / minute
Basic	15
Starter	150
Standard	300
Elite	600

You can check your current rate limit status by looking at the following HTTP headers which are returned in response to every API request.

X-RateLimit-Limit: 150
X-RateLimit-Remaining: 140

In case if you hit the rate limit, an 429 Too Many Requests HTTP response will be returned from the API and the following headers will also be present in the response:

Retry-After: 50
X-RateLimit-Reset: 1572168550

The Retry-After header indicates how long you need to wait until you can send the next request and the X-RateLimit-Reset header is the exact timestamp when the rate limiting will be reseted so you can again send the request to the API.

Authorization

Support Hub API uses the API key for authorization. You can find your API key from your profile section.

Any request that requires an authorized user expects this token to be supplied in the form of a Authorization header like so:

Authorization: Bearer {api_key}

When a API key has not been supplied, or the supplied API key is invalid, the API will return a 401 Unauthorized response with the following body:

{
    "message": "Unauthenticated."
}

Error Handling

The API returns a variety of errors and each error will contain a message property with the info about the error itself. The most common type of errors are the validation errors that will always be formatted like following:

{
    "message": "The given data was invalid.",
    "errors": {
        "first_name": [
            "The first name field is required."
        ],
        "last_name": [
            "The last name field is required."
        ],
        "email": [
            "The email field is required."
        ]
    }
}

Pagination

Some endpoints will return data in a paginated list. A paginated response will look similar to this:

{
    "data": [
        //...
    ],
    "links": {
        "first": "https://yoursubdomain.support-hub.io/api/tickets?page=1",
        "last": "https://yoursubdomain.support-hub.io/api/tickets?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "http://yoursubdomain.support-hub.io/api/tickets",
        "per_page": 15,
        "to": 15,
        "total": 15
    }
}

As per the example above, each paginated response will have the data array, which contains all the items from the specific page, a links object with full URLs for fetching first, last, prev and next pages, and the meta object which contains all the info about the resource you are paginating.

Some endpoints allow you to specific number of records that you want to receive per page. To achieve that you can append the per_page=X parameter to the URL of the request. For example, if you want to request 50 customers per page, the URL parameters should look like the following:

/customers?per_page=50

Pagination limit is set to 100 for most resources which means that you cannot request more than 100 records per page. If you provide a larger number, it will be ignored and 100 records per page will be returned.

To request a different page, just append the page=X parameter to the URL. For our customers example above, you can get the second page like following:

/customers?per_page=50&page=2

Filtering Results

Each section inside the docs that supports filtering will have a list of supported filters defined and you can specify as a query parameter while making the request.

Filters should be provided as a part of the enpoint URL in the following format:

?filter[FILTER_NAME]=VALUE

For example, lets say that you want to get all the customers that are named John. It can be done by providing the name filter while making the request:

customers?filter[name]=John

There are two different types of filters, the exact and partial filters.

Exact Filters

Exact filters will only return those records where a specific attribute is exactly the same as the provided filter value.

For example, if an endpoint supports an exact filter for filtering out the records by status and if you provide ?filter[status]=1 query parameter, only records that have the status attribute set to 1 will be returned.

Partial Filters

The partial filters are usually used for text based fields an it will return all the records that have the provided filter vaule anywhere within the attribute value.

For example, if there is a filter name defined for the specific resource and you provide the ?filter[name]=one filter within the URL, the API will return all the customers from the db that contain the word one anywhere within their name attribute and not only those who has the name exactly set as one.

Sorting Results

All sortable resources will provide the list of sortable fields that can be used for sorting the data that is being returned from the API.

To sort a resource by the specific field, just append the ?sort=FIELD query parameter while you make the request to the API endpoint and it will sort the items in ascending order. To sort the items in descending order, prefix the field with - sign: ?sort=-FIELD.

For example, if you want to sort the tickets in ascending order by the created_at timestamp, you should make a request to the following endpoint:

/tickets?sort=created_at

If you want to sort them by the created_at timestamp in descending order, the enpoint should be updated to look like the following:

/tickets?sort=-created_at

Including Related Entities

Support Hub API provides a convinient way to fetch some related resources while fetching a specific resource. For example, it can be pretty useful to get the info about the user who created a specific ticket while fetching the ticket itself.

If there are some supported includes for the specific endpoint, they will be provided inside the endpoint description. To specify which additional resources you want to include, just append the include query parameter to the URL, like following:

?include=resource1,resource2,...

For example, if you want to include the details about the user who created a ticket while fetching the ticket list, your query parameters will look like the following:

/tickets?include=user

Each ticket in the list of tickets returned by the API will now have the additional user object where you can find all the info about the user who created the ticket.