AreTheyHappy Public Api

Public REST API : 1.2

This document contains an overview of all methods/models/error codes applicable to the 1.2 version of the AreTheyHappy public REST API

Methods

An overview of the methods available in this version of the API

Management

GET /company

Lists all companies that have enabled your integration in AreTheyHappy

Possible response codes

200: Success
401: Access Denied
403: Access Forbidden
404: Not Found

Example response

[
    {
        "id": "24050",
        "name": "Acme Corp"
    },
    {
        "id": "25061",
        "name": "Northwind Group"
    }
]

GET /company/{company_id}

Retrieves a single company by its id

Parameters

path company_id: Id of the company

Possible response codes

200: Success
401: Access Denied
403: Access Forbidden
404: Not Found

Example response

{
    "id": "24050",
    "name": "Acme Corp"
}

GET /company/{company_id}/locations

Lists all locations for a single company

Parameters

path company_id: Id of the company

Possible response codes

200: Success
401: Access Denied
403: Access Forbidden
404: Not Found

Example response

[
    {
        "id": "120590",
        "name": "Acme Corp - London Office",
        "has_integrations": true,
        "contact_details": {
            "phone": "+32 010 23 45 67",
            "website": "example.com",
            "email": "[email protected]"
        },
        "address_details": {
            "street": "Kortrijksesteenweg 1070",
            "city": "Gent",
            "country": "BE",
            "zip": "9000",
            "lat": 51.031326,
            "lng": 3.708748
        }
    },
    {
        "id": "120590",
        "name": "Acme Corp - Glasgow",
        "has_integrations": true,
        "contact_details": {
            "phone": "+32 010 23 45 67",
            "website": "example.com",
            "email": "[email protected]"
        },
        "address_details": {
            "street": "Kortrijksesteenweg 1071",
            "city": "Gent",
            "country": "BE",
            "zip": "9000",
            "lat": 51.031326,
            "lng": 3.708748
        }
    }
]

GET /company/{company_id}/locations/{location_id}

Retrieves a single location by its id on a company by its id

Parameters

path company_id: Id of the company
path location_id: Id of the location

Possible response codes

200: Success
401: Access Denied
403: Access Forbidden
404: Not Found

Example response

{
    "id": "120590",
    "name": "Acme Corp - London Office",
    "has_integrations": true,
    "contact_details": {
        "phone": "+32 010 23 45 67",
        "website": "example.com",
        "email": "[email protected]"
    },
    "address_details": {
        "street": "Kortrijksesteenweg 1070",
        "city": "Gent",
        "country": "BE",
        "zip": "9000",
        "lat": 51.031326,
        "lng": 3.708748
    }
}

Insights

GET /company/{company_id}/insights/nps

Retrieves the nps evolution for a company by its id on a range of -100 to 100

Parameters

path company_id: Id of the company
query group_by: Group the result set
query start: Start date, can't be older than 1 year
query end: End date, can't be today, in the future or before start
query data_fn: Switch between cumulative and average NPS
query location_id: Comma delimited string of location ids that aggregate NPS need to be retrieved for

Possible response codes

200: Success
401: Access Denied
403: Access Forbidden
404: Not Found

Example response

[
    {
        "val": "52.24",
        "date": "2019-02-05"
    },
    {
        "val": "54.64",
        "date": "2019-02-06"
    }
]

GET /company/{company_id}/locations/{location_id}/insights/nps

Retrieves the nps evolution for a location on a company by the location_id and company_id on a range of -100 to 100

Parameters

path company_id: Id of the company
path location_id: Id of the location
query group_by: Group the result set
query start: Start date, can't be older than 1 year
query end: End date, can't be today, in the future or before start
query data_fn: Switch between cumulative and average NPS

Possible response codes

200: Success
401: Access Denied
403: Access Forbidden
404: Not Found

Example response

[
    {
        "val": "52.24",
        "date": "2019-02-05"
    },
    {
        "val": "54.64",
        "date": "2019-02-06"
    }
]

GET /company/{company_id}/insights/score

Retrieves the score evolution for a company by its id on a range of 0 to 5

Parameters

path company_id: Id of the company
query group_by: Group the result set
query start: Start date, can't be older than 1 year
query end: End date, can't be today, in the future or before start
query data_fn: Switch between cumulative and average score
query location_id: Comma delimited string of location ids that aggregate scores need to be retrieved for

Possible response codes

200: Success
401: Access Denied
403: Access Forbidden
404: Not Found

Example response

[
    {
        "val": "4.15",
        "date": "2019-02-05"
    },
    {
        "val": "4.32",
        "date": "2019-02-06"
    }
]

GET /company/{company_id}/locations/{location_id}/insights/score

Retrieves the score evolution for a location on a company by the location_id and company_id on a range of 0 to 5

Parameters

path company_id: Id of the company
path location_id: Id of the location
query group_by: Group the result set
query start: Start date, can't be older than 1 year
query end: End date, can't be today, in the future or before start
query data_fn: Switch between cumulative and average score

Possible response codes

200: Success
401: Access Denied
403: Access Forbidden
404: Not Found

Example response

[
    {
        "val": "4.15",
        "date": "2019-02-05"
    },
    {
        "val": "4.32",
        "date": "2019-02-06"
    }
]

Models

An overview of the models available in this version of the API

Company

id Unique id of the company

Type: Number Format: Long
name Name of the company

Type: String

Example

{
    "id": "24050",
    "name": "Acme Corp"
}

Location

id Unique id of the location

Type: Number Format: Long
name Name of the location

Type: String
has_integrations Whether or not the location has integrations connected

Type: Boolean
contact_details.phone Phone number of the location

Type: String
contact_details.website Website of the location

Type: String Format: url
contact_details.email Email of the location

Type: String Format: email
address_details.street Street portion of the address

Type: String
address_details.city City portion of the address

Type: String
address_details.country Country portion of the address

Type: String Format: ISO 3166-2
address_details.zip Zip code portion of the address

Type: String
address_details.lat Latitude coordinate of the location

Type: Number Format: Float Min: -90 Max: 90
address_details.lng Longitude coordinate of the location

Type: Number Format: Float Min: -180 Max: 180

Example

{
    "id": "120590",
    "name": "Acme Corp - London Office",
    "has_integrations": true,
    "contact_details": {
        "phone": "+32 010 23 45 67",
        "website": "example.com",
        "email": "[email protected]"
    },
    "address_details": {
        "street": "Kortrijksesteenweg 1070",
        "city": "Gent",
        "country": "BE",
        "zip": "9000",
        "lat": 51.031326,
        "lng": 3.708748
    }
}

Insights NPS

val NPS score for this period

Type: Number Format: Float Min: -100 Max: 100
date Date for this period (only when group_by = day)

Type: String Format: YYYY-MM-DD
start Start date for this period (only when group_by != day)

Type: String Format: YYYY-MM-DD
end End date for this period (only when group_by != day)

Type: String Format: YYYY-MM-DD

Example

{
    "val": "52.24",
    "date": "2019-02-05"
}

Insights Score

val The score for this period

Type: Number Format: Float Max: 5
date Date for this period (only when group_by = day)

Type: String Format: YYYY-MM-DD
start Start date for this period (only when group_by != day)

Type: String Format: YYYY-MM-DD
end End date for this period (only when group_by != day)

Type: String Format: YYYY-MM-DD

Example

{
    "val": "4.15",
    "date": "2019-02-05"
}

Error Codes

An overview of the custom error codes that will be sent as part of the meta object on 400 badrequest calls when validation errors occur

ERR:MSG:RATELIMITTED: Provided when a ratelimit (read/write) is hit
ERR:MSG:VALIDATION:MALFORMED: General catch-all for malformed parameters
ERR:MSG:VALIDATION:GROUP_BY_MALFORMED: Group by parameter is malformed
ERR:MSG:VALIDATION:GROUP_BY_UNKNOWN: Unknown group by parameter was passed
ERR:MSG:VALIDATION:DATA_FN_MALFORMED: Data Fn parameter is malformed
ERR:MSG:VALIDATION:DATA_FN_UNKNOWN: Unknown data fn parameter was passed
ERR:MSG:VALIDATION:LOCATION_IDS_MALFORMED: Location IDs parameter is malformed
ERR:MSG:VALIDATION:START_MALFORMED: Start date parameter is malformed
ERR:MSG:VALIDATION:START_FORMAT: Start date parameter was not in the correct format (YYYY-MM-DD)
ERR:MSG:VALIDATION:END_MALFORMED: End date parameter is malformed
ERR:MSG:VALIDATION:END_FORMAT: End date parameter was not in the correct format (YYYY-MM-DD)
ERR:MSG:VALIDATION:END_BEFORE_START: End date parameter was passed as being before start date
ERR:MSG:VALIDATION:END_EQUALS_START: End date parameter was passed as being equal to start date
ERR:MSG:VALIDATION:END_TODAY_OR_FUTURE: End date parameter was passed as being today or in the future
ERR:MSG:VALIDATION:START_TOO_OLD: Start date parameter is too old (can not be older than 1 year)