Public REST API

Getting started with the AreTheyHappy public REST API. This document provides you a global overview of the API architecture, navigate to the approriate version for version-specific information by using the version listing in the section titled "API Versions".

Please send us an e-mail with your use case at [email protected] if you would like to get access to the Public REST API

API Versions

We apply semver major/minor to our api versioning, meaning that all versions within the same minor number are backwards compatible with each other. Changes in major version might mean a breaking change between versions

Authentication

Authentication is done by providing your api key in the header of the requests.

X-ATH-APIKEY
XXXXXXXXX
Content-Type
application/json

An api key is linked to a specific app and environment, it needs to be requested through [email protected]. When the app has been approved and created we will send you your authentication key.

Environments

Each environment will have its own ApiKey for your integration, please contact [email protected] for a test company on our staging environment.

Response format

The response format is application/json and every response is wrapped in the following structure:

{
    "data" : {},
    "meta" : {},
    "warnings" : {}
}

This structure was chosen with a purpose to allow for more detailed data scenarios to be easily parsed on both front/backend.

Please find a description of these 3 categories below:

Example Success Response:

{
    "data" : {
        "id": 123456789,
        "name": "Acme Corp",
    },
    "meta" : {},
    "warnings" : {}
}

Example Failed Response:

{
    "data": {
        "status": 404,
        "detail": "The requested resource could not be found"
    },
    "meta": {},
    "warnings": {}
}

Example Failed Response with specific code:

{
    "data": {
        "status": 400,
        "detail": "Bad request"
    },
    "meta": {
        "code": "ERR:MSG:VALIDATION:START_FORMAT"
    },
    "warnings": {}
}

Webhooks

If configured, webhook requests will be sent as POST requests to the endpoint of your choice. Below you can find the list of all possible webhook events that we fire off:

Example webhook payload

{
    "data" : {
        "sent_at": 1564662600,
        "action": "APP:SUBSCRIBE",
        "payload": {
            "company_id": 999999,
            ...
        }
    },
    "meta" : {},
    "warnings" : {}
}

Please use the below table to fully understand the structure of our webhook events

Verifying webhook validity

If a webhook secret is configured, this secret will be sent along in the headers of the webhook request as the X-ATH-APISIGNATURE. The signature will be the configured secret hashed with SHA256

Example: Secret123456789 becomes

X-ATH-APISIGNATURE
65F09EAD6E19C1644277AFA8DDF63C3A073032FCB1866A1CFD514AD9EFADEF2E