🡰 Back to overview 1.3 Changelog

Public REST API : 1.3

This document contains an overview of all methods/models/error codes applicable to the 1.3 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

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

[
    {
        "id": 24050,
        "name": "Acme Corp",
        "score": 4.2,
        "created_at": "2022-02-06T18:27:13.000Z"
    },
    {
        "id": 25061,
        "name": "Northwind Group",
        "score": 4.6,
        "created_at": "2022-02-01T10:02:02.000Z"
    }
]
GET /company/{company_id}

Retrieves a single company by its id

Parameters

path company_id
Id of the company

Type Integer

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

{
    "id": 24050,
    "name": "Acme Corp",
    "score": 4.2,
    "created_at": "2022-02-06T18:27:13.000Z"
}
POST /company/{company_id}/authorize

Generate a SSO authentication link for a user on a company

Notes

  • Access to this endpoint is granted on a per client basis
  • You need to provide at least a user_id or user_email
  • Generating SSO authentication links for deactivated users/companies will be blocked off
  • Generating SSO authentication links for unverified users will be blocked off

Parameters

path company_id
Id of the company

Type Integer

body user_id
Id of the ATH User

Type Integer

body user_email
Email of the ATH User

Type String Format email

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

{
    "link": "https://xxx.aretheyhappy.com/xxx?..."
}
GET /company/{company_id}/locations

Lists all locations for a company

Parameters

path company_id
Id of the company

Type Integer

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

[
    {
        "id": 120590,
        "name": "Acme Corp - London Office",
        "alias": "Acme London",
        "score": 4.56,
        "has_integrations": true,
        "contact_details": {
            "phone": "+32 010 23 45 67",
            "website": "example.com",
            "email": "[email protected]"
        },
        "address_details": {
            "country": "BE",
            "region": "East-Flanders",
            "district": false,
            "zip": "9000",
            "city": "Gent",
            "street": "Kortrijksesteenweg 1070",
            "lat": 51.031326,
            "lng": 3.708748
        },
        "opening_hours": {
            "monday": [
                {
                    "from": "00:00",
                    "to": "24:00",
                    "is_open": false
                }
            ],
            "tuesday": [
                {
                    "from": "00:00",
                    "to": "24:00",
                    "is_open": false
                }
            ],
            "wednesday": [
                {
                    "from": "12:00",
                    "to": "22:00",
                    "is_open": true
                }
            ],
            "thursday": [
                {
                    "from": "12:00",
                    "to": "22:00",
                    "is_open": true
                }
            ],
            "friday": [
                {
                    "from": "12:00",
                    "to": "18:00",
                    "is_open": true
                },
                {
                    "from": "19:00",
                    "to": "23:00",
                    "is_open": true
                }
            ],
            "saturday": [
                {
                    "from": "12:00",
                    "to": "18:00",
                    "is_open": true
                },
                {
                    "from": "19:00",
                    "to": "23:00",
                    "is_open": true
                }
            ],
            "sunday": [
                {
                    "from": "00:00",
                    "to": "24:00",
                    "is_open": false
                }
            ]
        },
        "connections": {
            "google_mybusiness": {
                "url_page": "https://...",
                "url_feedback": "https://..."
            },
            "twitter": {
                "url_page": "https://...",
                "url_feedback": "https://..."
            },
            "facebook": {
                "url_page": "https://...",
                "url_feedback": "https://..."
            }
        },
        "created_at": "2022-02-06T18:27:13.000Z"
    },
    {
        "id": 120591,
        "name": "Acme Corp - Glasgow",
        "alias": false,
        "score": 4.56,
        "has_integrations": true,
        "contact_details": {
            "phone": "+32 010 23 45 67",
            "website": "example.com",
            "email": "[email protected]"
        },
        "address_details": {
            "country": "BE",
            "region": "East-Flanders",
            "district": false,
            "zip": "9000",
            "city": "Gent",
            "street": "Kortrijksesteenweg 1071",
            "lat": 51.031326,
            "lng": 3.708748
        },
        "opening_hours": false,
        "connections": {
            "tripadvisor": {
                "url_page": "https://...",
                "url_feedback": "https://..."
            },
            "facebook": {
                "url_page": "https://...",
                "url_feedback": "https://..."
            }
        },
        "created_at": "2022-02-04T13:59:10.000Z"
    }
]
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

Type Integer

path location_id
Id of the location

Type Integer

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

{
    "id": 120590,
    "name": "Acme Corp - London Office",
    "alias": "Acme London",
    "score": 4.56,
    "has_integrations": true,
    "contact_details": {
        "phone": "+32 010 23 45 67",
        "website": "example.com",
        "email": "[email protected]"
    },
    "address_details": {
        "country": "BE",
        "region": "East-Flanders",
        "district": false,
        "zip": "9000",
        "city": "Gent",
        "street": "Kortrijksesteenweg 1070",
        "lat": 51.031326,
        "lng": 3.708748
    },
    "opening_hours": {
        "monday": [
            {
                "from": "00:00",
                "to": "24:00",
                "is_open": false
            }
        ],
        "tuesday": [
            {
                "from": "00:00",
                "to": "24:00",
                "is_open": false
            }
        ],
        "wednesday": [
            {
                "from": "12:00",
                "to": "22:00",
                "is_open": true
            }
        ],
        "thursday": [
            {
                "from": "12:00",
                "to": "22:00",
                "is_open": true
            }
        ],
        "friday": [
            {
                "from": "12:00",
                "to": "18:00",
                "is_open": true
            },
            {
                "from": "19:00",
                "to": "23:00",
                "is_open": true
            }
        ],
        "saturday": [
            {
                "from": "12:00",
                "to": "18:00",
                "is_open": true
            },
            {
                "from": "19:00",
                "to": "23:00",
                "is_open": true
            }
        ],
        "sunday": [
            {
                "from": "00:00",
                "to": "24:00",
                "is_open": false
            }
        ]
    },
    "connections": {
        "google_mybusiness": {
            "url_page": "https://...",
            "url_feedback": "https://..."
        },
        "twitter": {
            "url_page": "https://...",
            "url_feedback": "https://..."
        },
        "facebook": {
            "url_page": "https://...",
            "url_feedback": "https://..."
        }
    },
    "created_at": "2022-02-06T18:27:13.000Z"
}

Insights

GET /company/{company_id}/insights/nps

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

Notes

  • Difference between start and end can not be bigger than 366 days

Parameters

path company_id
Id of the company

Type Integer

query group_by
Group the result set

Type string Default day Enum day,week,month,quarter

query start
Start date, can't be older than 5 years

Type string Format YYYY-MM-DD Default 1 month ago Example 2019-08-01

query end
End date, can't be today, in the future or before start

Type string Format YYYY-MM-DD Default yesterday Example 2019-08-15

query data_fn
Switch between cumulative and average NPS

Type string Enum cum,avg

query location_ids
Comma delimited string of location ids that aggregate NPS need to be retrieved for

Type String

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

[
    {
        "start": "2021-01-01",
        "end": "2021-03-31",
        "val": 32.65,
        "amt": 1774,
        "pos": 827,
        "det": 250,
        "neu": 690
    },
    {
        "start": "2021-04-01",
        "end": "2021-06-30",
        "val": 32.94,
        "amt": 1913,
        "pos": 901,
        "det": 273,
        "neu": 732
    },
    {
        "start": "2021-07-01",
        "end": "2021-09-30",
        "val": 32.96,
        "amt": 2431,
        "pos": 1125,
        "det": 326,
        "neu": 973
    },
    {
        "start": "2021-10-01",
        "end": "2021-12-31",
        "val": 32.31,
        "amt": 2597,
        "pos": 1185,
        "det": 348,
        "neu": 1057
    }
]
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

Notes

  • Difference between start and end can not be bigger than 366 days

Parameters

path company_id
Id of the company

Type Integer

path location_id
Id of the location

Type Integer

query group_by
Group the result set

Type string Default day Enum day,week,month,quarter

query start
Start date, can't be older than 5 years

Type string Format YYYY-MM-DD Default 1 month ago Example 2019-08-01

query end
End date, can't be today, in the future or before start

Type string Format YYYY-MM-DD Default yesterday Example 2019-08-15

query data_fn
Switch between cumulative and average NPS

Type string Enum cum,avg

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

[
    {
        "start": "2021-01-01",
        "end": "2021-03-31",
        "val": 32.65,
        "amt": 1774,
        "pos": 827,
        "det": 250,
        "neu": 690
    },
    {
        "start": "2021-04-01",
        "end": "2021-06-30",
        "val": 32.94,
        "amt": 1913,
        "pos": 901,
        "det": 273,
        "neu": 732
    },
    {
        "start": "2021-07-01",
        "end": "2021-09-30",
        "val": 32.96,
        "amt": 2431,
        "pos": 1125,
        "det": 326,
        "neu": 973
    },
    {
        "start": "2021-10-01",
        "end": "2021-12-31",
        "val": 32.31,
        "amt": 2597,
        "pos": 1185,
        "det": 348,
        "neu": 1057
    }
]
GET /company/{company_id}/insights/score

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

Notes

  • Difference between start and end can not be bigger than 366 days

Parameters

path company_id
Id of the company

Type Integer

query group_by
Group the result set

Type string Default day Enum day,week,month,quarter

query start
Start date, can't be older than 5 years

Type string Format YYYY-MM-DD Default 1 month ago Example 2019-08-01

query end
End date, can't be today, in the future or before start

Type string Format YYYY-MM-DD Default yesterday Example 2019-08-15

query data_fn
Switch between cumulative and average score

Type string Enum cum,avg

query location_ids
Comma delimited string of location ids that aggregate scores need to be retrieved for

Type String

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

[
    {
        "start": "2021-01-01",
        "end": "2021-03-31",
        "val": 4.06,
        "amt": 1774,
        "r1": 39,
        "r2": 55,
        "r3": 179,
        "r4": 757,
        "r5": 737
    },
    {
        "start": "2021-04-01",
        "end": "2021-06-30",
        "val": 4.06,
        "amt": 1913,
        "r1": 47,
        "r2": 58,
        "r3": 191,
        "r4": 799,
        "r5": 811
    },
    {
        "start": "2021-07-01",
        "end": "2021-09-30",
        "val": 4.06,
        "amt": 2431,
        "r1": 53,
        "r2": 71,
        "r3": 225,
        "r4": 1041,
        "r5": 1034
    },
    {
        "start": "2021-10-01",
        "end": "2021-12-31",
        "val": 4.05,
        "amt": 2597,
        "r1": 56,
        "r2": 78,
        "r3": 237,
        "r4": 1125,
        "r5": 1094
    }
]
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

Notes

  • Difference between start and end can not be bigger than 366 days

Parameters

path company_id
Id of the company

Type Integer

path location_id
Id of the location

Type Integer

query group_by
Group the result set

Type string Default day Enum day,week,month,quarter

query start
Start date, can't be older than 5 years

Type string Format YYYY-MM-DD Default 1 month ago Example 2019-08-01

query end
End date, can't be today, in the future or before start

Type string Format YYYY-MM-DD Default yesterday Example 2019-08-15

query data_fn
Switch between cumulative and average score

Type string Enum cum,avg

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

[
    {
        "start": "2021-01-01",
        "end": "2021-03-31",
        "val": 4.06,
        "amt": 1774,
        "r1": 39,
        "r2": 55,
        "r3": 179,
        "r4": 757,
        "r5": 737
    },
    {
        "start": "2021-04-01",
        "end": "2021-06-30",
        "val": 4.06,
        "amt": 1913,
        "r1": 47,
        "r2": 58,
        "r3": 191,
        "r4": 799,
        "r5": 811
    },
    {
        "start": "2021-07-01",
        "end": "2021-09-30",
        "val": 4.06,
        "amt": 2431,
        "r1": 53,
        "r2": 71,
        "r3": 225,
        "r4": 1041,
        "r5": 1034
    },
    {
        "start": "2021-10-01",
        "end": "2021-12-31",
        "val": 4.05,
        "amt": 2597,
        "r1": 56,
        "r2": 78,
        "r3": 237,
        "r4": 1125,
        "r5": 1094
    }
]

Feed

GET /company/{company_id}/feed/all_reviews

Lists all reviews for a company

Notes

  • Access to this endpoint is granted on a per client basis
  • Reviews returned will be no older than 6 months
  • Only reviews longer than 10 characters will be returned by default (set allow_empty=1 to adjust this)
  • Only public reviews will be returned, set (allow_private=1 to adjust this)
  • Review text is automatically truncated to 512 characters, set (no_trunc=1 to adjust this)
  • Each page of reviews is capped at 15 reviews, use the page_nr parameter to paginate to the next page

Parameters

path company_id
Id of the company

Type Integer

query location_ids
Comma delimited string of location ids for this company to retrieve reviews for

Type String

query integrations
Comma delimited string of integrations to pull reviews for

Type string Enum facebook,tripadvisor,google_mybusiness,yelp,formitable,tablemanager,eetnu,zomato,resengo,manual_review,takeaway,booking,ifood,deliveroo,uber_eats

query page_nr
The page number

Type Integer Default 1 Min 1

query allow_empty
Whether or not reviews that are empty or below 10 characters should be returned

Type Boolean (1=true, 0=false) Default 0

query allow_private
Whether or not private reviews should be returned

Type Boolean (1=true, 0=false) Default 0

query no_trunc
Whether or not truncation should happen

Type Boolean (1=true, 0=false) Default 0

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

{
    "count": 2,
    "surveys": [
        {
            "ath_id": "de13234...",
            "location_ids": [
                120591
            ],
            "integration_type": "yelp",
            "rating": 4,
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
            "lang": "nl",
            "is_anonymous": false,
            "is_private": false,
            "is_truncated": false,
            "is_empty": false,
            "username": "Jane Smith",
            "avatar": "https://...png",
            "tags": [
                {
                    "lbl": "Slow staff",
                    "sentiment": "negative",
                    "category": "service"
                },
                {
                    "lbl": "Cold Coffee",
                    "sentiment": "negative",
                    "category": "food"
                }
            ],
            "date_posted": "2020-02-08 20:34:19.000Z"
        },
        {
            "ath_id": "cf134...",
            "location_ids": [
                120590
            ],
            "integration_type": "tripadvisor",
            "rating": 5,
            "subratings": {
                "rate_service": 4,
                "rate_value": 5,
                "rate_food": 5
            },
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
            "lang": "en",
            "is_anonymous": false,
            "is_private": false,
            "is_truncated": false,
            "is_empty": false,
            "username": "John Doe",
            "avatar": "https://...png",
            "attachments": [
                {
                    "type": "image",
                    "src": "https://...png"
                }
            ],
            "tags": [
                {
                    "lbl": "Cold Coffee",
                    "sentiment": "negative",
                    "category": "food"
                }
            ],
            "date_posted": "2020-02-16 14:23:24.000Z"
        }
    ]
}
GET /company/{company_id}/feed/best_reviews

Lists the top X reviews for a company

Notes

  • Reviews returned will be no older than 6 months
  • Only reviews longer than 10 characters will be returned by default (set allow_empty=1 to adjust this)
  • Only public reviews will be returned, set (allow_private=1 to adjust this)
  • Review text is automatically truncated to 512 characters, set (no_trunc=1 to adjust this)

Parameters

path company_id
Id of the company

Type Integer

query location_ids
Comma delimited string of location ids for this company to retrieve reviews for

Type String

query integrations
Comma delimited string of integrations to pull best reviews for

Type string Enum facebook,tripadvisor,google_mybusiness,yelp,formitable,tablemanager,eetnu,zomato,resengo,manual_review,takeaway,booking,ifood,deliveroo,uber_eats

query limit
The amount of reviews to be returned

Type Integer Default 10 Min 1 Max 15

query allow_empty
Whether or not reviews that are empty or below 10 characters should be returned

Type Boolean (1=true, 0=false) Default 0

query allow_private
Whether or not private reviews should be returned

Type Boolean (1=true, 0=false) Default 0

query no_trunc
Whether or not truncation should happen

Type Boolean (1=true, 0=false) Default 0

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

{
    "count": 2,
    "surveys": [
        {
            "ath_id": "de13234...",
            "location_ids": [
                120591
            ],
            "integration_type": "yelp",
            "rating": 4,
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
            "lang": "nl",
            "is_anonymous": false,
            "is_private": false,
            "is_truncated": false,
            "is_empty": false,
            "username": "Jane Smith",
            "avatar": "https://...png",
            "tags": [
                {
                    "lbl": "Slow staff",
                    "sentiment": "negative",
                    "category": "service"
                },
                {
                    "lbl": "Cold Coffee",
                    "sentiment": "negative",
                    "category": "food"
                }
            ],
            "date_posted": "2020-02-08 20:34:19.000Z"
        },
        {
            "ath_id": "cf134...",
            "location_ids": [
                120590
            ],
            "integration_type": "tripadvisor",
            "rating": 5,
            "subratings": {
                "rate_service": 4,
                "rate_value": 5,
                "rate_food": 5
            },
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
            "lang": "en",
            "is_anonymous": false,
            "is_private": false,
            "is_truncated": false,
            "is_empty": false,
            "username": "John Doe",
            "avatar": "https://...png",
            "attachments": [
                {
                    "type": "image",
                    "src": "https://...png"
                }
            ],
            "tags": [
                {
                    "lbl": "Cold Coffee",
                    "sentiment": "negative",
                    "category": "food"
                }
            ],
            "date_posted": "2020-02-16 14:23:24.000Z"
        }
    ]
}
GET /company/{company_id}/feed/sampled_reviews

Lists a sample set of reviews for a company

Notes

  • Reviews returned will be no older than 6 months
  • Sampling for the different limit_* props is done individually and the result is shuffled using Fisher-Yates before being returned (set do_shuffle=0 to not apply shuffling)
  • Only reviews longer than 10 characters will be returned (set allow_empty=1 to adjust this)
  • Only public reviews will be returned, set (allow_private=1 to adjust this)
  • Review text is automatically truncated to 512 characters, set (no_trunc=1 to adjust this)

Parameters

path company_id
Id of the company

Type Integer

query location_ids
Comma delimited string of location ids for this company to retrieve reviews for

Type String

query integrations
Comma delimited string of integrations to pull sampled reviews for

Type string Enum facebook,tripadvisor,google_mybusiness,yelp,formitable,tablemanager,eetnu,zomato,resengo,manual_review,takeaway,booking,ifood,deliveroo,uber_eats

query limit
The amount of reviews to be returned

Type Integer Default 10 Min 1 Max 15

query limit_5
The max amount of 5-star reviews to be returned

Type Integer Default 5 Max 5

query limit_4
The max amount of 4-star reviews to be returned

Type Integer Default 5 Max 5

query limit_3
The max amount of 3-star reviews to be returned

Type Integer Max 5

query allow_empty
Whether or not reviews that are empty or below 10 characters should be returned

Type Boolean (1=true, 0=false) Default 0

query allow_private
Whether or not private reviews should be returned

Type Boolean (1=true, 0=false) Default 0

query no_trunc
Whether or not truncation should happen

Type Boolean (1=true, 0=false) Default 0

query do_shuffle
Whether or not to shuffle/randomize reviews

Type Boolean (1=true, 0=false) Default 1

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

{
    "count": 2,
    "surveys": [
        {
            "ath_id": "de13234...",
            "location_ids": [
                120591
            ],
            "integration_type": "yelp",
            "rating": 4,
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
            "lang": "nl",
            "is_anonymous": false,
            "is_private": false,
            "is_truncated": false,
            "is_empty": false,
            "username": "Jane Smith",
            "avatar": "https://...png",
            "tags": [
                {
                    "lbl": "Slow staff",
                    "sentiment": "negative",
                    "category": "service"
                },
                {
                    "lbl": "Cold Coffee",
                    "sentiment": "negative",
                    "category": "food"
                }
            ],
            "date_posted": "2020-02-08 20:34:19.000Z"
        },
        {
            "ath_id": "cf134...",
            "location_ids": [
                120590
            ],
            "integration_type": "tripadvisor",
            "rating": 5,
            "subratings": {
                "rate_service": 4,
                "rate_value": 5,
                "rate_food": 5
            },
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
            "lang": "en",
            "is_anonymous": false,
            "is_private": false,
            "is_truncated": false,
            "is_empty": false,
            "username": "John Doe",
            "avatar": "https://...png",
            "attachments": [
                {
                    "type": "image",
                    "src": "https://...png"
                }
            ],
            "tags": [
                {
                    "lbl": "Cold Coffee",
                    "sentiment": "negative",
                    "category": "food"
                }
            ],
            "date_posted": "2020-02-16 14:23:24.000Z"
        }
    ]
}
POST /company/{company_id}/feed/bulk_upload

Upload a data file containing reviews/feedback and have its contents automatically parsed and imported into the AreTheyHappy inbox based on a preconfigured template (eg: Deliveroo Order Reviews)

Help Articles

Notes

  • Access to this endpoint is granted on a per client basis
  • This endpoint has a limit of 10 calls per day
  • Maximum file upload size is 25 Megabyte per request
  • Ensure the file that file_url is pointing to is publicly accessible
  • At the moment we only support CSV files
  • Template Ids are provided by AreTheyHappy support as they are customized to the data payload you are providing.
  • Location Mappings need to be correct, each location in the mapping needs to belong to the company you are making the request for
  • On job start: A FEED:BULK_UPLOAD:STARTED webhook is sent out
  • On job finish: A FEED:BULK_UPLOAD:FINISHED webhook is sent out containing some additional results

Parameters

path company_id
Id of the company

Type Integer

body file_url
URL for externally hosted file to be uploaded

Type File Format csv

body template_id
Id of the AreTheyHappy template to use for parsing the contents

Type String

body mapping
Array of objects with mapping of location to identifier in the file, passed as a JSON string or JSON array

Type Array Format UploadMappingObject

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

{
    "job_id": "xxxxxx-xxxx-xxxxx-xxxxxx"
}
GET /company/{company_id}/locations/{location_id}/feed/all_reviews

Lists all reviews for a company

Notes

  • Access to this endpoint is granted on a per client basis
  • Reviews returned will be no older than 6 months
  • Only reviews longer than 10 characters will be returned by default (set allow_empty=1 to adjust this)
  • Only public reviews will be returned, set (allow_private=1 to adjust this)
  • Review text is automatically truncated to 512 characters, set (no_trunc=1 to adjust this)
  • Each page of reviews is capped at 15 reviews, use the page_nr parameter to paginate to the next page

Parameters

path company_id
Id of the company

Type Integer

path location_id
Id of the location

Type Integer

query integrations
Comma delimited string of integrations to pull reviews for

Type string Enum facebook,tripadvisor,google_mybusiness,yelp,formitable,tablemanager,eetnu,zomato,resengo,manual_review,takeaway,booking,ifood,deliveroo,uber_eats

query page_nr
The page number

Type Integer Default 1 Min 1

query allow_empty
Whether or not reviews that are empty or below 10 characters should be returned

Type Boolean (1=true, 0=false) Default 0

query allow_private
Whether or not private reviews should be returned

Type Boolean (1=true, 0=false) Default 0

query no_trunc
Whether or not truncation should happen

Type Boolean (1=true, 0=false) Default 0

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

{
    "count": 2,
    "surveys": [
        {
            "ath_id": "de13234...",
            "location_ids": [
                120591
            ],
            "integration_type": "yelp",
            "rating": 4,
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
            "lang": "nl",
            "is_anonymous": false,
            "is_private": false,
            "is_truncated": false,
            "is_empty": false,
            "username": "Jane Smith",
            "avatar": "https://...png",
            "tags": [
                {
                    "lbl": "Slow staff",
                    "sentiment": "negative",
                    "category": "service"
                },
                {
                    "lbl": "Cold Coffee",
                    "sentiment": "negative",
                    "category": "food"
                }
            ],
            "date_posted": "2020-02-08 20:34:19.000Z"
        },
        {
            "ath_id": "cf134...",
            "location_ids": [
                120590
            ],
            "integration_type": "tripadvisor",
            "rating": 5,
            "subratings": {
                "rate_service": 4,
                "rate_value": 5,
                "rate_food": 5
            },
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
            "lang": "en",
            "is_anonymous": false,
            "is_private": false,
            "is_truncated": false,
            "is_empty": false,
            "username": "John Doe",
            "avatar": "https://...png",
            "attachments": [
                {
                    "type": "image",
                    "src": "https://...png"
                }
            ],
            "tags": [
                {
                    "lbl": "Cold Coffee",
                    "sentiment": "negative",
                    "category": "food"
                }
            ],
            "date_posted": "2020-02-16 14:23:24.000Z"
        }
    ]
}
GET /company/{company_id}/locations/{location_id}/feed/best_reviews

Lists the top X reviews for a location in a company

Notes

  • Reviews returned will be no older than 6 months
  • Only reviews longer than 10 characters will be returned by default (set allow_empty=1 to adjust this)
  • Only public reviews will be returned, set (allow_private=1 to adjust this)
  • Review text is automatically truncated to 512 characters, set (no_trunc=1 to adjust this)

Parameters

path company_id
Id of the company

Type Integer

path location_id
Id of the location

Type Integer

query integrations
Comma delimited string of integrations to pull best reviews for

Type string Enum facebook,tripadvisor,google_mybusiness,yelp,formitable,tablemanager,eetnu,zomato,resengo,manual_review,takeaway,booking,ifood,deliveroo,uber_eats

query limit
The amount of reviews to be returned

Type Integer Default 10 Min 1 Max 15

query allow_empty
Whether or not reviews that are empty or below 10 characters should be returned

Type Boolean (1=true, 0=false) Default 0

query allow_private
Whether or not private reviews should be returned

Type Boolean (1=true, 0=false) Default 0

query no_trunc
Whether or not truncation should happen

Type Boolean (1=true, 0=false) Default 0

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

{
    "count": 2,
    "surveys": [
        {
            "ath_id": "de13234...",
            "location_ids": [
                120591
            ],
            "integration_type": "yelp",
            "rating": 4,
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
            "lang": "nl",
            "is_anonymous": false,
            "is_private": false,
            "is_truncated": false,
            "is_empty": false,
            "username": "Jane Smith",
            "avatar": "https://...png",
            "tags": [
                {
                    "lbl": "Slow staff",
                    "sentiment": "negative",
                    "category": "service"
                },
                {
                    "lbl": "Cold Coffee",
                    "sentiment": "negative",
                    "category": "food"
                }
            ],
            "date_posted": "2020-02-08 20:34:19.000Z"
        },
        {
            "ath_id": "cf134...",
            "location_ids": [
                120590
            ],
            "integration_type": "tripadvisor",
            "rating": 5,
            "subratings": {
                "rate_service": 4,
                "rate_value": 5,
                "rate_food": 5
            },
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
            "lang": "en",
            "is_anonymous": false,
            "is_private": false,
            "is_truncated": false,
            "is_empty": false,
            "username": "John Doe",
            "avatar": "https://...png",
            "attachments": [
                {
                    "type": "image",
                    "src": "https://...png"
                }
            ],
            "tags": [
                {
                    "lbl": "Cold Coffee",
                    "sentiment": "negative",
                    "category": "food"
                }
            ],
            "date_posted": "2020-02-16 14:23:24.000Z"
        }
    ]
}
GET /company/{company_id}/locations/{location_id}/feed/sampled_reviews

Lists a sample set of reviews for a location in a company

Notes

  • Reviews returned will be no older than 6 months
  • Sampling for the different limit_* props is done individually and the result is shuffled using Fisher-Yates before being returned (set do_shuffle=0 to not apply shuffling)
  • Only reviews longer than 10 characters will be returned (set allow_empty=1 to adjust this)
  • Only public reviews will be returned, set (allow_private=1 to adjust this)
  • Review text is automatically truncated to 512 characters, set (no_trunc=1 to adjust this)

Parameters

path company_id
Id of the company

Type Integer

path location_id
Id of the location

Type Integer

query integrations
Comma delimited string of integrations to pull sampled reviews for

Type string Enum facebook,tripadvisor,google_mybusiness,yelp,formitable,tablemanager,eetnu,zomato,resengo,manual_review,takeaway,booking,ifood,deliveroo,uber_eats

query limit
The amount of reviews to be returned

Type Integer Default 10 Min 1 Max 15

query limit_5
The max amount of 5-star reviews to be sampled

Type Integer Default 5 Max 5

query limit_4
The max amount of 4-star reviews to be sampled

Type Integer Default 5 Max 5

query limit_3
The max amount of 3-star reviews to be sampled

Type Integer Max 5

query allow_empty
Whether or not reviews that are empty or below 10 characters should be returned

Type Boolean (1=true, 0=false) Default 0

query allow_private
Whether or not private reviews should be returned

Type Boolean (1=true, 0=false) Default 0

query no_trunc
Whether or not truncation should happen

Type Boolean (1=true, 0=false) Default 0

query do_shuffle
Whether or not to shuffle/randomize reviews

Type Boolean (1=true, 0=false) Default 1

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

{
    "count": 2,
    "surveys": [
        {
            "ath_id": "de13234...",
            "location_ids": [
                120591
            ],
            "integration_type": "yelp",
            "rating": 4,
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
            "lang": "nl",
            "is_anonymous": false,
            "is_private": false,
            "is_truncated": false,
            "is_empty": false,
            "username": "Jane Smith",
            "avatar": "https://...png",
            "tags": [
                {
                    "lbl": "Slow staff",
                    "sentiment": "negative",
                    "category": "service"
                },
                {
                    "lbl": "Cold Coffee",
                    "sentiment": "negative",
                    "category": "food"
                }
            ],
            "date_posted": "2020-02-08 20:34:19.000Z"
        },
        {
            "ath_id": "cf134...",
            "location_ids": [
                120590
            ],
            "integration_type": "tripadvisor",
            "rating": 5,
            "subratings": {
                "rate_service": 4,
                "rate_value": 5,
                "rate_food": 5
            },
            "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
            "lang": "en",
            "is_anonymous": false,
            "is_private": false,
            "is_truncated": false,
            "is_empty": false,
            "username": "John Doe",
            "avatar": "https://...png",
            "attachments": [
                {
                    "type": "image",
                    "src": "https://...png"
                }
            ],
            "tags": [
                {
                    "lbl": "Cold Coffee",
                    "sentiment": "negative",
                    "category": "food"
                }
            ],
            "date_posted": "2020-02-16 14:23:24.000Z"
        }
    ]
}

Surveys

GET /company/{company_id}/surveys

Lists all live surveys for a company

Notes

  • Access to this endpoint is granted on a per client basis
  • Only live surveys will be returned by default

Parameters

path company_id
Id of the company

Type Integer

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

[
    {
        "id": "cf134...",
        "name": "Welcome Survey",
        "url": "https://areyouhappy.com/...",
        "public_title": "AreTheyHappy Welcome Survey",
        "public_description": "Welcome to AreTheyHappy, please fill in the following survey about your experience",
        "score": 81,
        "response_amt": 194,
        "response_div": {
            "0": 0,
            "1": 3,
            "2": 7,
            "3": 2,
            "4": 53,
            "5": 31,
            "6": 13,
            "7": 42,
            "8": 25,
            "9": 14,
            "10": 4
        },
        "created_at": "2020-02-16 14:23:24.000Z"
    },
    {
        "id": "cf134...",
        "name": "Post-Dinner Survey",
        "url": "https://areyouhappy.com/...",
        "public_title": "AreTheyHappy Post-Dinner Survey",
        "public_description": "How was your dinner? Please fill in the following survey about your experience",
        "score": 75,
        "response_amt": 150,
        "response_div": {
            "0": 0,
            "1": 0,
            "2": 0,
            "3": 0,
            "4": 0,
            "5": 0,
            "6": 0,
            "7": 75,
            "8": 75,
            "9": 0,
            "10": 0
        },
        "created_at": "2020-02-16 14:23:24.000Z"
    }
]
GET /company/{company_id}/surveys/{survey_id}

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

Notes

  • Access to this endpoint is granted on a per client basis

Parameters

path company_id
Id of the company

Type Integer

path survey_id
Id of the survey

Type String

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

{
    "id": "cf134...",
    "name": "Welcome Survey",
    "url": "https://areyouhappy.com/...",
    "public_title": "AreTheyHappy Welcome Survey",
    "public_description": "Welcome to AreTheyHappy, please fill in the following survey about your experience",
    "score": 81,
    "response_amt": 194,
    "response_div": {
        "0": 0,
        "1": 3,
        "2": 7,
        "3": 2,
        "4": 53,
        "5": 31,
        "6": 13,
        "7": 42,
        "8": 25,
        "9": 14,
        "10": 4
    },
    "created_at": "2020-02-16 14:23:24.000Z"
}
GET /company/{company_id}/surveys/{survey_id}/responses

Retrieves responses for a single survey by its id on a company by its id

Notes

  • Responses returned will be no older than 6 months
  • Access to this endpoint is granted on a per client basis
  • Each page of responses is capped at 15 responses, use the page_nr parameter to paginate to the next page

Parameters

path company_id
Id of the company

Type Integer

path survey_id
Id of the survey

Type String

query location_ids
Comma delimited string of location ids for this company to retrieve reviews for

Type String

query page_nr
The page number

Type Integer Default 1 Min 1

query start
Start date, can't be older than 6 months

Type string Format YYYY-MM-DD Default 1 month ago Example 2019-08-01

query has_consent
Whether the respondent gave consent

Type Boolean (1=true, 0=false)

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

{
    "count": 2,
    "responses": [
        {
            "ath_id": "eb782059f553a10a690d57495e8a2c09",
            "location_id": 7,
            "name": "Jane Doe",
            "email": false,
            "phone": false,
            "has_consent": false,
            "score": 100,
            "completed": false,
            "answers": [
                {
                    "question": "How satisfied are you with our service?",
                    "question_id": "c07f8b48-6f4b-4438-9217-98cfd6744227",
                    "type": "star",
                    "answer": 5,
                    "skip": false
                },
                {
                    "question": "Can you tell us a bit more why you rated us this way?",
                    "question_id": "b31161e1-30e9-422f-a2b3-7c85725df30b",
                    "type": "freeform",
                    "answer": false,
                    "skip": true
                }
            ],
            "created_at": "2021-11-24T16:02:54.000Z"
        },
        {
            "ath_id": "ed2b44cfc32b23af1a67993612874c4a",
            "location_id": 18,
            "name": "John Doe",
            "email": "[email protected]",
            "phone": false,
            "has_consent": true,
            "score": 80,
            "completed": true,
            "answers": [
                {
                    "question": "How satisfied are you with our service?",
                    "question_id": "c07f8b48-6f4b-4438-9217-98cfd6744227",
                    "type": "star",
                    "answer": 4,
                    "skip": false
                },
                {
                    "question": "Can you tell us a bit more why you rated us this way?",
                    "question_id": "b31161e1-30e9-422f-a2b3-7c85725df30b",
                    "type": "freeform",
                    "answer": "The service was slow",
                    "skip": false
                }
            ],
            "created_at": "2022-01-10T23:00:30.000Z"
        }
    ]
}

Models

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

Authorize

  • link Authorization Link to be redirected to

    Type String

Example

{
    "link": "https://xxx.aretheyhappy.com/xxx?..."
}

Company

  • id Unique id of the company

    Type Number Format Long

  • name Name of the company

    Type String

  • score Last score of the company

    Type Number Format Float Min 0 Max 5 Fallback false

  • created_at Creation timestamp

    Type String

Notes

  • Score will be set to false if no score is found

Example

{
    "id": 24050,
    "name": "Acme Corp",
    "score": 4.2,
    "created_at": "2022-02-06T18:27:13.000Z"
}

Location

  • id Unique id of the location

    Type Number Format Long

  • name Name of the location

    Type String

  • alias Alias of the location

    Type String Fallback false

  • score Last score of the location

    Type Number Format Float Min 0 Max 5 Fallback false

  • has_integrations Whether or not the location has integrations connected

    Type Boolean

  • connections KV map of connected channel links for publicly accessible pages

    Type KV(integrationtype => LocationConnection)

  • 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.country Country portion of the address

    Type String Format ISO 3166-2

  • address_details.region Top-Level sub-national administrative Area (eg: state/province)

    Type String

  • address_details.district Smaller than Top-Level sub-national administrative feature but larger than city (eg: prefectures in China)

    Type String

  • address_details.zip Postal code used in country-specific national addressing system

    Type String

  • address_details.city City/Municipality/Village

    Type String

  • address_details.street Individual Residential/Business address (street + nr)

    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

  • opening_hours.monday Opening hour schedule for monday

    Type Array[LocationHourSlot]

  • opening_hours.tuesday Opening hour schedule for tuesday

    Type Array[LocationHourSlot]

  • opening_hours.wednesday Opening hour schedule for wednesday

    Type Array[LocationHourSlot]

  • opening_hours.thursday Opening hour schedule for thursday

    Type Array[LocationHourSlot]

  • opening_hours.friday Opening hour schedule for friday

    Type Array[LocationHourSlot]

  • opening_hours.saturday Opening hour schedule for saturday

    Type Array[LocationHourSlot]

  • opening_hours.sunday Opening hour schedule for monday

    Type Array[LocationHourSlot]

  • created_at Creation timestamp

    Type String

Notes

  • Opening Hours will be set to false if not configured
  • Score will be set to false if no score is found
  • Alias will be set to false if not configured
  • The integrations included for location connections are facebook, twitter, instagram, yelp, tripadvisor, google_mybusiness, eetnu, booking, takeaway, foursquare

Example

{
    "id": 120590,
    "name": "Acme Corp - London Office",
    "alias": "Acme London",
    "score": 4.56,
    "has_integrations": true,
    "contact_details": {
        "phone": "+32 010 23 45 67",
        "website": "example.com",
        "email": "[email protected]"
    },
    "address_details": {
        "country": "BE",
        "region": "East-Flanders",
        "district": false,
        "zip": "9000",
        "city": "Gent",
        "street": "Kortrijksesteenweg 1070",
        "lat": 51.031326,
        "lng": 3.708748
    },
    "opening_hours": {
        "monday": [
            {
                "from": "00:00",
                "to": "24:00",
                "is_open": false
            }
        ],
        "tuesday": [
            {
                "from": "00:00",
                "to": "24:00",
                "is_open": false
            }
        ],
        "wednesday": [
            {
                "from": "12:00",
                "to": "22:00",
                "is_open": true
            }
        ],
        "thursday": [
            {
                "from": "12:00",
                "to": "22:00",
                "is_open": true
            }
        ],
        "friday": [
            {
                "from": "12:00",
                "to": "18:00",
                "is_open": true
            },
            {
                "from": "19:00",
                "to": "23:00",
                "is_open": true
            }
        ],
        "saturday": [
            {
                "from": "12:00",
                "to": "18:00",
                "is_open": true
            },
            {
                "from": "19:00",
                "to": "23:00",
                "is_open": true
            }
        ],
        "sunday": [
            {
                "from": "00:00",
                "to": "24:00",
                "is_open": false
            }
        ]
    },
    "connections": {
        "google_mybusiness": {
            "url_page": "https://...",
            "url_feedback": "https://..."
        },
        "twitter": {
            "url_page": "https://...",
            "url_feedback": "https://..."
        },
        "facebook": {
            "url_page": "https://...",
            "url_feedback": "https://..."
        }
    },
    "created_at": "2022-02-06T18:27:13.000Z"
}

LocationConnection

  • url_page Public page link for a connected channel (eg: tripadvisor restaurant page)

    Type String Format url Fallback false

  • url_feedback Public 'write a review' link for a connected channel (eg: Google write a review page)

    Type String Format url Fallback false

Notes

  • The integrations included for location connections are facebook, twitter, instagram, yelp, tripadvisor, google_mybusiness, eetnu, booking, takeaway, foursquare
  • Both url_page and url_feedback will fallback to false if not available

Example

{
    "url_page": "https://...",
    "url_feedback": "https://..."
}

LocationHourSlot

  • from Start time of the slot

    Type String Format HH:MM

  • to End time of the slot

    Type String Format HH:MM

  • is_open Open/Closed at this point in time

    Type Boolean

Example

{
    "from": "12:00",
    "to": "18:00",
    "is_open": true
}

Insights NPS

  • val NPS score for this period

    Type Number Format Float Min -100 Max 100

  • amt The amount of feedback items the NPS score is based on

    Type Number Format Integer

  • pos The amount of promotors

    Type Number Format Integer

  • neu The amount of passives

    Type Number Format Integer

  • det The amount of detractors

    Type Number Format Integer

  • 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

  • _f Returned as true when the record represents a period with no data

    Type Boolean

Notes

  • _f will only be set if it is a blank record
  • Difference between start and end can not be bigger than 366 days
  • Start can not be older than 5 years ago

Example

{
    "start": "2021-10-01",
    "end": "2021-12-31",
    "val": 32.31,
    "amt": 2597,
    "pos": 1185,
    "det": 348,
    "neu": 1057
}

Insights Score

  • val The score for this period

    Type Number Format Float Min 0 Max 5

  • amt The amount of feedback items the score is based on

    Type Number Format Integer

  • r1 Amount of feedback items that would be 1 on a 1-5 scale

    Type Number Format Integer

  • r2 Amount of feedback items that would be 2 on a 1-5 scale

    Type Number Format Integer

  • r3 Amount of feedback items that would be 3 on a 1-5 scale

    Type Number Format Integer

  • r4 Amount of feedback items that would be 4 on a 1-5 scale

    Type Number Format Integer

  • r5 Amount of feedback items that would be 5 on a 1-5 scale

    Type Number Format Integer

  • 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

  • _f Returned as true when the record represents a period with no data

    Type Boolean

Notes

  • _f will only be set if it is a blank record
  • Difference between start and end can not be bigger than 366 days
  • Start can not be older than 5 years ago

Example

{
    "start": "2021-10-01",
    "end": "2021-12-31",
    "val": 4.05,
    "amt": 2597,
    "r1": 56,
    "r2": 78,
    "r3": 237,
    "r4": 1125,
    "r5": 1094
}

Review

  • ath_id Hashed id of the review

    Type String

  • location_ids Array of AreTheyHappy Location Ids

    Type Array[Integer]

  • integration_type The type of integration this came from

    Type string Enum facebook,tripadvisor,google_mybusiness,yelp,formitable,tablemanager,eetnu,zomato,resengo,manual_review,takeaway,booking,ifood,deliveroo,uber_eats

  • rating The rating score

    Type Number Format Float

  • subratings (optional) Subratings scores for the review

    Type String Format json

  • title (optional) Title of the review

    Type String

  • text The textual content of the review

    Type String

  • lang Language of the review

    Type String Format ISO-639 Example en

  • is_anonymous Whether or not this user is anonymous

    Type Boolean

  • is_private Whether or not this review can be shown publicly

    Type Boolean

  • is_empty Whether or not this review has any form of content

    Type Boolean

  • is_truncated Whether or not this review was truncated

    Type Boolean

  • username The name of the reviewer

    Type String

  • avatar (optional) Reviewer avatar

    Type String Format url

  • attachments Attachments that the reviewer added (eg: images, videos, links)

    Type Array[ReviewAttachment]

  • tags AreTheyHappy tags applied to the review

    Type Array[ReviewTag]

  • date_posted The date the review was written

    Type String

Example

{
    "ath_id": "cf134...",
    "location_ids": [
        120590
    ],
    "integration_type": "tripadvisor",
    "rating": 5,
    "subratings": {
        "rate_service": 4,
        "rate_value": 5,
        "rate_food": 5
    },
    "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.",
    "lang": "en",
    "is_anonymous": false,
    "is_private": false,
    "is_truncated": false,
    "is_empty": false,
    "username": "John Doe",
    "avatar": "https://...png",
    "attachments": [
        {
            "type": "image",
            "src": "https://...png"
        }
    ],
    "tags": [
        {
            "lbl": "Cold Coffee",
            "sentiment": "negative",
            "category": "food"
        }
    ],
    "date_posted": "2020-02-16 14:23:24.000Z"
}

ReviewAttachment

  • type The type of attachment

    Type string Enum image,video,link,file,audio,card

  • src Source link of the attachment

    Type String Format url

  • name (optional) Name of the attachment

    Type String

  • title (optional) Title of the attachment

    Type String

  • description (optional) Description of the attachment

    Type String

ReviewTag

  • lbl Tag label

    Type String

  • sentiment Tag sentiment

    Type string Enum negative,neutral,positive

  • category Tag Category

    Type string Enum experience,food,consistency,service,environment,reputation,convenience,value,innovation,family_friendly

Notes

  • These are AreTheyHappy tags applied by users within the platform or automatically through our Flow feature

Example

{
    "lbl": "Slow staff",
    "sentiment": "negative",
    "category": "service"
}

UploadMappingObject

  • id Id of the AreTheyHappy Location to map to

    Type Number Format Integer

  • name Name in the file being uploaded that maps to this location

    Type String

Example

[
    {
        "id": 1,
        "name": "AreTheyHappy - Ghent"
    },
    {
        "id": 2,
        "name": "AreTheyHappy - Antwerp"
    }
]

Survey

  • id Unique id of the survey

    Type String

  • name Name of the survey

    Type String

  • public_title The public title of the survey that is displayed on the tabs name

    Type String

  • public_description The survey description which is set as meta description on the survey page

    Type String

  • url The url of the survey

    Type String Format url

  • score Last score of the survey

    Type Number Format Float Min 0 Max 100 Fallback false

  • response_amt The total number of responses

    Type Number Format Integer

  • response_div Distribution of the answers on a 0 to 10 scale

    Type Object

  • created_at Creation timestamp

    Type String

Notes

  • Score will be set to false if no score could be calculated due to either no responses or no responses with value questions answered

Example

{
    "id": "cf134...",
    "name": "Welcome Survey",
    "url": "https://areyouhappy.com/...",
    "public_title": "AreTheyHappy Welcome Survey",
    "public_description": "Welcome to AreTheyHappy, please fill in the following survey about your experience",
    "score": 81,
    "response_amt": 194,
    "response_div": {
        "0": 0,
        "1": 3,
        "2": 7,
        "3": 2,
        "4": 53,
        "5": 31,
        "6": 13,
        "7": 42,
        "8": 25,
        "9": 14,
        "10": 4
    },
    "created_at": "2020-02-16 14:23:24.000Z"
}

Survey Response

  • id Hashed id of the survey response

    Type String

  • location_id AreTheyHappy Location Id

    Type String

  • name The name of the respondent

    Type String

  • email The email of the respondent

    Type String

  • phone The phone number of the respondent

    Type String

  • has_consent Whether the repondent gave his consent

    Type Boolean

  • score The score calculated based on the answers

    Type Number Format Float Min 0 Max 100 Fallback false

  • completed Whether the repondent finished the survey

    Type Boolean

  • answers An array of all answers

    Type Array[SurveyAnswer]

  • created_at Creation timestamp

    Type String

Notes

  • name will default to false if not provided
  • email will default to false if not provided
  • phone will default to false if not provided
  • Score will be set to false if no values questions were answered

Example

{
    "ath_id": "ed2b44cfc32b23af1a67993612874c4a",
    "location_id": 18,
    "name": "John Doe",
    "email": "[email protected]",
    "phone": false,
    "has_consent": true,
    "score": 80,
    "completed": true,
    "answers": [
        {
            "question": "How satisfied are you with our service?",
            "question_id": "c07f8b48-6f4b-4438-9217-98cfd6744227",
            "type": "star",
            "answer": 4,
            "skip": false
        },
        {
            "question": "Can you tell us a bit more why you rated us this way?",
            "question_id": "b31161e1-30e9-422f-a2b3-7c85725df30b",
            "type": "freeform",
            "answer": "The service was slow",
            "skip": false
        }
    ],
    "created_at": "2022-01-10T23:00:30.000Z"
}

Survey Answer

  • question The survey question text

    Type String

  • question_id The id of the survey question

    Type String

  • type The question type

    Type string Enum nps,ces,csat,star,smileys,yesno,freeform,choice,ath_review_link

  • answer The respondent's answer (depends on question type)

    Type Mixed

  • skip Whether the repondent skipped this question

    Type Boolean

Notes

  • Skip is set to true if the respondent skipped this answer
  • Answer value type depends on question type

    type: star will have either false or an integer in the range of 1-5 as their value (low-to-high)

    type: nps will have either false or an integer in the range of 0-10 as their value (low-to-high)

    type: yesno will have either false, 0 (no) or 1 (yes) as their value

    type: csat will have either false or an integer in the range of 1-5 as their value (low-to-high)

    type: ces will have either false or an integer in the range of 1-5 as their value (low-to-high)

    type: smileys will have either false or an integer in the range of 1-5 as their value (low-to-high)

    type: freeform will have either a string or false as their value

    type: choice will have an array of objects representing the selected options in the following format:
    [{"val": "coffee"}, {"val": "wine"}]
    Answers that fall outside of the provided options will have a boolean flag is_other appended to them:
    [{"val": "coffee"}, {"val": "soda", "is_other": true}]
    type: ath_review_link special question type only available in the 'generate more reviews' survey, will have an object as its answer in the following format:
    {"itype": "google_mybusiness", "clicked": 1}
    where clicked is 0 or 1 depending on whether or not they clicked on the platform-redirect button. itype represents the integration that was redirected to.

Example

{
    "question": "How satisfied are you with our service?",
    "question_id": "c07f8b48-6f4b-4438-9217-98cfd6744227",
    "type": "star",
    "answer": 4,
    "skip": false
}

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:ACL_MISSING_SCOPE
Your api client key does not have permission to use this endpoint
ERR:MSG:AUTHORIZE_NOAC
The user/company you were authorizing does not exist or has been deactivated
ERR:MSG:UNKNOWN
An unknown error occurred
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:DATERANGE_BOUNDS
The selected date range is too large
ERR:MSG:VALIDATION:DATERANGE_TOO_OLD
The selected date range has a start date which is too old
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:START_TOO_OLD
Start date parameter is too old (can not be older than 1 year)
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:LIMIT_MALFORMED
Limit parameter is malformed
ERR:MSG:VALIDATION:PAGE_NR_MALFORMED
Page nr is malformed
ERR:MSG:VALIDATION:INTEGRATIONS_MALFORMED
Integrations parameter is malformed
ERR:MSG:VALIDATION:INTEGRATIONS_UNKNOWN
Unknown integrations parameter was passed
ERR:MSG:VALIDATION:UPLOAD_FILE_TOO_LARGE
The provided file is too large
ERR:MSG:VALIDATION:UPLOAD_FILE_TYPE
The provided file is not of the correct type
ERR:MSG:VALIDATION:UPLOAD_FILE_MALFORMED
The provided file does not contain the required structure
ERR:MSG:VALIDATION:UPLOAD_MAPPING_MALFORMED
The provided mapping is malformed or contains unknown entries
ERR:MSG:VALIDATION:UPLOAD_TEMPLATE_UNKNOWN
The provided bulk upload template is unknown