SupportPal Documentation

REST API

The SupportPal REST API can be used to access data and perform actions available in SupportPal from external applications.

Contents

Authentication

SupportPal uses Basic Access Authentication. To authenticate with the API you must first create an API token in the core settings. Afterwards, simply specify the API token as the username - there is no need to provide a password.

Examples

In all the below examples, the API Token is: "fos4Tp45mC=wsdYqvc?z#ZW4d!h7U3JB". A dummy password of value "X" is also provided.

CURL
    curl -v -u fos4Tp45mC=wsdYqvc?z#ZW4d!h7U3JB:X -H "Content-Type: application/json" -X GET https://www.mydomain.com/api/selfservice/type
    /**
     * Interfaces with API via cURL. Function handles, GET, POST, PUT & DELETE.
     *
     * Usage Examples:
     *   - _doAPICall('user/user'); -- Returns a list of all users
     *   - _doAPICall('user/user', array('email' => 'test@test.com')); -- Returns details on a single user identified by email address
     *   - _doAPICall('user/user', array('fullname' => 'Test User', 'password' => 'test', 'email' => 'test@test.com'), 'POST'); -- Creates a new user
     *   - _doAPICall('user/user', array('id' => 1), 'DELETE'); -- Deletes a user identified by ID
     *
     * @param   string  $apiCall  The API function that we want to use
     * @param   array   $data     The data for the API function parameters
     * @param   string  $method   If we're using GET, POST, PUT or DELETE, uses GET by default
     * @return  mixed
     */
    function _doAPICall($apiCall, $data = array(), $method = 'GET')
    {
        // Variables
        $baseUrl = 'https://www.mydomain.com/api/';
        $apiToken = 'fos4Tp45mC=wsdYqvc?z#ZW4d!h7U3JB';

        // Start cURL
        $c = curl_init();
        curl_setopt($c, CURLOPT_CONNECTTIMEOUT, 5);
        curl_setopt($c, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($c, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
        curl_setopt($c, CURLOPT_USERPWD, $apiToken . ":x");

        // Start building the URL
        $apiCall = $baseUrl . $apiCall;

        // Check what type of API call we are making
        if ($method == 'GET') {
            // Add the array of data to the URL
            if (is_array($data)) {
                $apiCall .= "?";
                foreach ($data as $key => $value) {
                    if (isset($value)) {
                        if (is_array($value)) {
                            // In case we have an array for a value, add each item of array
                            foreach ($value as $arrayKey => $arrayValue) {
                                $apiCall .= $key . '[' . $arrayKey . ']' . "=" . $arrayValue . "&";
                            }
                        } else {
                            $apiCall .= $key . "=" . $value . "&";
                        }
                    }
                }

                // Remove the final &
                $apiCall = rtrim($apiCall, '&');
            }
        } elseif ($method == 'PUT' || $method == 'DELETE') {
            // PUT and DELETE require an $id variable to be appended to the URL
            if (isset($data['id'])) {
                $apiCall .= "/" . $data['id'];
            }

            // Setup the remainder of the cURL request
            curl_setopt($c, CURLOPT_POSTFIELDS, http_build_query($data));
            curl_setopt($c, CURLOPT_HTTPHEADER, array('X-HTTP-Method-Override: ' . $method));
        } else {
            // Setup the remainder of the cURL request
            curl_setopt($c, CURLOPT_POST, true);
            curl_setopt($c, CURLOPT_POSTFIELDS, http_build_query($data));
        }

        // Set the URL
        curl_setopt($c, CURLOPT_URL, $apiCall);

        // Execute the API call and return the response
        $result = curl_exec($c);
        curl_close($c);

        // Return the results of the API call
        return $result;
    }

Language

If you're using multi-language translations, by default, the API will return the default value of content and translations will be accessible as a relation in the results. If you're running the API for a given user with a known language, you may append lang as a parameter to the request to retrieve results in that language if a translation exists for it.

Below is an example of fetching the Open status with and without the language param (set to French).

http://www.mydomain.com/api/ticket/status/1

    {
        "status": "success",
        "message": null,
        "data": {
            "id": 1,
            "name": "Open",
            "colour": "#35a600",
            "auto_close": 1,
            "order": 1,
            "created_at": 1486732738,
            "updated_at": 1486732738,
            "translations": [
                {
                    "status_id": 1,
                    "name": "Ouvrir",
                    "locale": "fr"
                }
            ]
        }
    }

http://www.mydomain.com/api/ticket/status/1?lang=fr

    {
        "status": "success",
        "message": null,
        "data": {
            "id": 1,
            "name": "Ouvrir",
            "colour": "#35a600",
            "auto_close": 1,
            "order": 1,
            "created_at": 1486732738,
            "updated_at": 1486732738,
            "translations": [
                {
                    "status_id": 1,
                    "name": "Ouvrir",
                    "locale": "fr"
                }
            ]
        }
    }

API Reference

View the complete API reference.