HappySignals API

A description of the customer facing API available in the HappySignals Analytics tool.

The API uses a REST style interfaces returning JSON formatted responses. Endpoints are hosted on the base url https://<client>.<environment>.happysignals.com/api/v2/<endpoint> where client is the current instance name, environment is the name of the environment where the instance is located, and endpoint is the relevant resource accessed. See the supported endpoints below.

Access control

Access to the API is controlled by means of a shared secret in the form of a unique API-token per client. To aquire your API-key get in touch with HappySignals support.

The token must be passed with each request to the API, either in the 'api_key' GET or POST parameter or as a bearer token in an Authorization HTTP header.

Please note that the API key must be base64 encoded if used in the Authorization header as per RFC6750.

Collection envelope

Collection resources return responses in a JSON formatted envelope containing the results and metadata about the results such as the total number of results and pagination information.

{
    "meta": {
        "count": <total number of results>,
        "page": <current page>,
        "pages": <total number of pages>
    },
    "items": [
        <array of result objects>
    ]
}

Query syntax

Collection resources generally allow filtering. Use the standard Django ORM query syntax to apply lookups that filter returned data. Filters may be passed either as GET or POST parameters.

The following restricted set of lookups are permitted:

An additional lookup ne that is not part of the standard Django set is provided to exclude values.

Results can be sorted using the "order" parameter by passing the field or fields (separated by comma) to sort on. Sorting can be reversed on a field by field basis by prefixing the field name with -, the default sorting is ascending.

GET /api/v2/responses?order=createdAt,-value

Use the "page" parameter to navigate long resultsets. Pages start from 1 and run up to the number of pages specified in the meta section of the response.

GET /api/v2/responses?page=3

Endpoints

/responses

A queryable collection of all responses received. Filtering is allowed on all fields except factors.

The following example demonstrates requesting responses where email is non empty and language is any of fi, sv, or en.

Request:

GET /api/v2/responses?email__ne=&language__in=fi,sv,en HTTP/1.1
Host: corp.emea.happysignals.com
Authorization: Bearer MWQ0OTVmNmYzZGU4YmZkZjc5ZGM=

Response:

HTTP/1.0 200 OK
Date: Tue, 28 Aug 2018 07:56:16 GMT
Content-Length: 358238
Content-Type: application/json

{
    "items": [
        {
            "timestamp": 1551958721476254,
            "configurationItem": "Office 365", 
            "ticketType": "Incident", 
            "secondaryCategory": "Collaboration Services", 
            "ticketId": "INC0851563", 
            "vendor": "ACME", 
            "subcompany": "", 
            "priority": "3", 
            "enterpriseClass": "IT", 
            "sourceSystem": null, 
            "email": "foo@example.com", 
            "sentDate": "", 
            "location": "Amsterdam Office", 
            "category": "Inquiry Help", 
            "tertiaryCategory": "Calendar", 
            "assignment": "Global Service Desk", 
            "company": "Acme Europe", 
            "language": "en", 
            "lostTime": 149, 
            "contactType": "Email",
            "service": "Accounts",
            "country": "NL", 
            "createdAt": "2016-12-31T08:27:32.237", 
            "topcompany": "", 
            "value": 10, 
            "profile": "doer", 
            "reassign": "0", 
            "region": "EMEA", 
            "comment": null, 
            "factors": [
                {"id": "deadbeef-dead-beef-deadbeef", "title": "Service personnel's attitude"},
                {"id": "beefdead-beef-dead-beefdead", "title": "Speed of service"}
            ]
        },
        ....
    ],
    "meta": {
        "count": 1234,
        "page": 2,
        "pages": 12
    }
}

/questionnaire/<slug>/responses

A queryable collection of responses received to questionnaire with identifier slug. Filtering is allowed on all fields except factors.

The following example demonstrates requesting responses to a questionnaire with slug f8f243929757bc121c75 where value is greater than or equal to 7, ordered by descending priority, showing page 2 of results.

Request:

GET /api/v2/questionnaires/f8f243929757bc121c75/responses?value__gte=7&order=-priority&page=2 HTTP/1.1
Host: corp.emea.happysignals.com
Authorization: Bearer MWQ0OTVmNmYzZGU4YmZkZjc5ZGM=

Response:

HTTP/1.0 200 OK
Date: Tue, 28 Aug 2018 07:56:16 GMT
Content-Length: 358238
Content-Type: application/json

{
    "items": [
        {
            "timestamp": 1551958721476254,
            "configurationItem": "Office 365", 
            "ticketType": "Incident", 
            "secondaryCategory": "Collaboration Services", 
            ...
        },
        ....
    ],
    "meta": {
        "count": 213,
        "page": 1,
        "pages": 9
    }
}