🡰 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

TypeInteger

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

TypeInteger

body user_id
Id of the ATH User

TypeInteger

body user_email
Email of the ATH User

TypeString Formatemail

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

TypeInteger

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

TypeInteger

path location_id
Id of the location

TypeInteger

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

TypeInteger

query group_by
Group the result set

Typestring Defaultday Enumday,week,month,quarter

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

Typestring FormatYYYY-MM-DD Default1 month ago Example2019-08-01

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

Typestring FormatYYYY-MM-DD Defaultyesterday Example2019-08-15

query data_fn
Switch between cumulative and average NPS

Typestring Enumcum,avg

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

TypeString

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

TypeInteger

path location_id
Id of the location

TypeInteger

query group_by
Group the result set

Typestring Defaultday Enumday,week,month,quarter

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

Typestring FormatYYYY-MM-DD Default1 month ago Example2019-08-01

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

Typestring FormatYYYY-MM-DD Defaultyesterday Example2019-08-15

query data_fn
Switch between cumulative and average NPS

Typestring Enumcum,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

TypeInteger

query group_by
Group the result set

Typestring Defaultday Enumday,week,month,quarter

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

Typestring FormatYYYY-MM-DD Default1 month ago Example2019-08-01

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

Typestring FormatYYYY-MM-DD Defaultyesterday Example2019-08-15

query data_fn
Switch between cumulative and average score

Typestring Enumcum,avg

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

TypeString

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

TypeInteger

path location_id
Id of the location

TypeInteger

query group_by
Group the result set

Typestring Defaultday Enumday,week,month,quarter

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

Typestring FormatYYYY-MM-DD Default1 month ago Example2019-08-01

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

Typestring FormatYYYY-MM-DD Defaultyesterday Example2019-08-15

query data_fn
Switch between cumulative and average score

Typestring Enumcum,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

TypeInteger

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

TypeString

query integrations
Comma delimited string of integrations to pull reviews for

Typestring Enumfacebook,tripadvisor,google_mybusiness,yelp,formitable,tablemanager,eetnu,zomato,resengo,manual_review,takeaway,booking,ifood,deliveroo,uber_eats,paytronix

query page_nr
The page number

TypeInteger Default1 Min1

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

TypeBoolean (1=true, 0=false) Default0

query allow_private
Whether or not private reviews should be returned

TypeBoolean (1=true, 0=false) Default0

query no_trunc
Whether or not truncation should happen

TypeBoolean (1=true, 0=false) Default0

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

TypeInteger

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

TypeString

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

Typestring Enumfacebook,tripadvisor,google_mybusiness,yelp,formitable,tablemanager,eetnu,zomato,resengo,manual_review,takeaway,booking,ifood,deliveroo,uber_eats,paytronix

query limit
The amount of reviews to be returned

TypeInteger Default10 Min1 Max15

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

TypeBoolean (1=true, 0=false) Default0

query allow_private
Whether or not private reviews should be returned

TypeBoolean (1=true, 0=false) Default0

query no_trunc
Whether or not truncation should happen

TypeBoolean (1=true, 0=false) Default0

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

TypeInteger

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

TypeString

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

Typestring Enumfacebook,tripadvisor,google_mybusiness,yelp,formitable,tablemanager,eetnu,zomato,resengo,manual_review,takeaway,booking,ifood,deliveroo,uber_eats,paytronix

query limit
The amount of reviews to be returned

TypeInteger Default10 Min1 Max15

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

TypeInteger Default5 Max5

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

TypeInteger Default5 Max5

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

TypeInteger Max5

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

TypeBoolean (1=true, 0=false) Default0

query allow_private
Whether or not private reviews should be returned

TypeBoolean (1=true, 0=false) Default0

query no_trunc
Whether or not truncation should happen

TypeBoolean (1=true, 0=false) Default0

query do_shuffle
Whether or not to shuffle/randomize reviews

TypeBoolean (1=true, 0=false) Default1

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

Import a single inbox feed item and have its contents automatically parsed and imported into the AreTheyHappy inbox based on a preconfigured template (eg: webform submisson)

Notes

  • Access to this endpoint is granted on a per client basis
  • Template Ids are provided by AreTheyHappy support as they are customized to the data payload you are providing.
  • On job start: A FEED:UPLOAD:STARTED webhook is sent out
  • On job finish: A FEED:UPLOAD:FINISHED webhook is sent out

Parameters

path company_id
Id of the company

TypeInteger

body location_id
Id of the location

TypeInteger

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

TypeString

body payload
Payload for the inbox feed item, content depends on the template the template_id is linked to

TypeObject

Response codes

200
Success
401
Access Denied
403
Access Forbidden
404
Not Found

Example response

{
    "job_id": "xxxxxx-xxxx-xxxxx-xxxxxx"
}
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 50 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

TypeInteger

body file_url
URL for externally hosted file to be uploaded

TypeFile Formatcsv

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

TypeString

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

TypeArray FormatUploadMappingObject

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

TypeInteger

path location_id
Id of the location

TypeInteger

query integrations
Comma delimited string of integrations to pull reviews for

Typestring Enumfacebook,tripadvisor,google_mybusiness,yelp,formitable,tablemanager,eetnu,zomato,resengo,manual_review,takeaway,booking,ifood,deliveroo,uber_eats,paytronix

query page_nr
The page number

TypeInteger Default1 Min1

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

TypeBoolean (1=true, 0=false) Default0

query allow_private
Whether or not private reviews should be returned

TypeBoolean (1=true, 0=false) Default0

query no_trunc
Whether or not truncation should happen

TypeBoolean (1=true, 0=false) Default0

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

TypeInteger

path location_id
Id of the location

TypeInteger

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

Typestring Enumfacebook,tripadvisor,google_mybusiness,yelp,formitable,tablemanager,eetnu,zomato,resengo,manual_review,takeaway,booking,ifood,deliveroo,uber_eats,paytronix

query limit
The amount of reviews to be returned

TypeInteger Default10 Min1 Max15

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

TypeBoolean (1=true, 0=false) Default0

query allow_private
Whether or not private reviews should be returned

TypeBoolean (1=true, 0=false) Default0

query no_trunc
Whether or not truncation should happen

TypeBoolean (1=true, 0=false) Default0

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

TypeInteger

path location_id
Id of the location

TypeInteger

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

Typestring Enumfacebook,tripadvisor,google_mybusiness,yelp,formitable,tablemanager,eetnu,zomato,resengo,manual_review,takeaway,booking,ifood,deliveroo,uber_eats,paytronix

query limit
The amount of reviews to be returned

TypeInteger Default10 Min1 Max15

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

TypeInteger Default5 Max5

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

TypeInteger Default5 Max5

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

TypeInteger Max5

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

TypeBoolean (1=true, 0=false) Default0

query allow_private
Whether or not private reviews should be returned

TypeBoolean (1=true, 0=false) Default0

query no_trunc
Whether or not truncation should happen

TypeBoolean (1=true, 0=false) Default0

query do_shuffle
Whether or not to shuffle/randomize reviews

TypeBoolean (1=true, 0=false) Default1

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

TypeInteger

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

TypeInteger

path survey_id
Id of the survey

TypeString

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

TypeInteger

path survey_id
Id of the survey

TypeString

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

TypeString

query page_nr
The page number

TypeInteger Default1 Min1

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

Typestring FormatYYYY-MM-DD Default1 month ago Example2019-08-01

query has_consent
Whether the respondent gave consent

TypeBoolean (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

    TypeString

Example

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

Company

  • id Unique id of the company

    TypeNumber FormatLong

  • name Name of the company

    TypeString

  • score Last score of the company

    TypeNumber FormatFloat Min0 Max5 Fallbackfalse

  • created_at Creation timestamp

    TypeString

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

    TypeNumber FormatLong

  • name Name of the location

    TypeString

  • alias Alias of the location

    TypeString Fallbackfalse

  • score Last score of the location

    TypeNumber FormatFloat Min0 Max5 Fallbackfalse

  • has_integrations Whether or not the location has integrations connected

    TypeBoolean

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

    TypeKV(integrationtype => LocationConnection)

  • contact_details.phone Phone number of the location

    TypeString

  • contact_details.website Website of the location

    TypeString Formaturl

  • contact_details.email Email of the location

    TypeString Formatemail

  • address_details.country Country portion of the address

    TypeString FormatISO 3166-2

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

    TypeString

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

    TypeString

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

    TypeString

  • address_details.city City/Municipality/Village

    TypeString

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

    TypeString

  • address_details.lat Latitude coordinate of the location

    TypeNumber FormatFloat Min-90 Max90

  • address_details.lng Longitude coordinate of the location

    TypeNumber FormatFloat Min-180 Max180

  • opening_hours.monday Opening hour schedule for monday

    TypeArray[LocationHourSlot]

  • opening_hours.tuesday Opening hour schedule for tuesday

    TypeArray[LocationHourSlot]

  • opening_hours.wednesday Opening hour schedule for wednesday

    TypeArray[LocationHourSlot]

  • opening_hours.thursday Opening hour schedule for thursday

    TypeArray[LocationHourSlot]

  • opening_hours.friday Opening hour schedule for friday

    TypeArray[LocationHourSlot]

  • opening_hours.saturday Opening hour schedule for saturday

    TypeArray[LocationHourSlot]

  • opening_hours.sunday Opening hour schedule for monday

    TypeArray[LocationHourSlot]

  • created_at Creation timestamp

    TypeString

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)

    TypeString Formaturl Fallbackfalse

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

    TypeString Formaturl Fallbackfalse

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

    TypeString FormatHH:MM

  • to End time of the slot

    TypeString FormatHH:MM

  • is_open Open/Closed at this point in time

    TypeBoolean

Example

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

Insights NPS

  • val NPS score for this period

    TypeNumber FormatFloat Min-100 Max100

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

    TypeNumber FormatInteger

  • pos The amount of promotors

    TypeNumber FormatInteger

  • neu The amount of passives

    TypeNumber FormatInteger

  • det The amount of detractors

    TypeNumber FormatInteger

  • date Date for this period (only when group_by = day)

    TypeString FormatYYYY-MM-DD

  • start Start date for this period (only when group_by != day)

    TypeString FormatYYYY-MM-DD

  • end End date for this period (only when group_by != day)

    TypeString FormatYYYY-MM-DD

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

    TypeBoolean

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

    TypeNumber FormatFloat Min0 Max5

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

    TypeNumber FormatInteger

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

    TypeNumber FormatInteger

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

    TypeNumber FormatInteger

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

    TypeNumber FormatInteger

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

    TypeNumber FormatInteger

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

    TypeNumber FormatInteger

  • date Date for this period (only when group_by = day)

    TypeString FormatYYYY-MM-DD

  • start Start date for this period (only when group_by != day)

    TypeString FormatYYYY-MM-DD

  • end End date for this period (only when group_by != day)

    TypeString FormatYYYY-MM-DD

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

    TypeBoolean

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

    TypeString

  • location_ids Array of AreTheyHappy Location Ids

    TypeArray[Integer]

  • integration_type The type of integration this came from

    Typestring Enumfacebook,tripadvisor,google_mybusiness,yelp,formitable,tablemanager,eetnu,zomato,resengo,manual_review,takeaway,booking,ifood,deliveroo,uber_eats,paytronix

  • rating The rating score

    TypeNumber FormatFloat

  • subratings (optional) Subratings scores for the review

    TypeString Formatjson

  • title (optional) Title of the review

    TypeString

  • text The textual content of the review

    TypeString

  • lang Language of the review

    TypeString FormatISO-639 Exampleen

  • is_anonymous Whether or not this user is anonymous

    TypeBoolean

  • is_private Whether or not this review can be shown publicly

    TypeBoolean

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

    TypeBoolean

  • is_truncated Whether or not this review was truncated

    TypeBoolean

  • username The name of the reviewer

    TypeString

  • avatar (optional) Reviewer avatar

    TypeString Formaturl

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

    TypeArray[ReviewAttachment]

  • tags AreTheyHappy tags applied to the review

    TypeArray[ReviewTag]

  • date_posted The date the review was written

    TypeString

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

    Typestring Enumimage,video,link,file,audio,card

  • src Source link of the attachment

    TypeString Formaturl

  • name (optional) Name of the attachment

    TypeString

  • title (optional) Title of the attachment

    TypeString

  • description (optional) Description of the attachment

    TypeString

ReviewTag

  • lbl Tag label

    TypeString

  • sentiment Tag sentiment

    Typestring Enumnegative,neutral,positive

  • category Tag Category

    Typestring Enumexperience,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

    TypeNumber FormatInteger

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

    TypeString

Example

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

Survey

  • id Unique id of the survey

    TypeString

  • name Name of the survey

    TypeString

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

    TypeString

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

    TypeString

  • url The url of the survey

    TypeString Formaturl

  • score Last score of the survey

    TypeNumber FormatFloat Min0 Max100 Fallbackfalse

  • response_amt The total number of responses

    TypeNumber FormatInteger

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

    TypeObject

  • created_at Creation timestamp

    TypeString

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

    TypeString

  • location_id AreTheyHappy Location Id

    TypeString

  • name The name of the respondent

    TypeString

  • email The email of the respondent

    TypeString

  • phone The phone number of the respondent

    TypeString

  • has_consent Whether the repondent gave his consent

    TypeBoolean

  • score The score calculated based on the answers

    TypeNumber FormatFloat Min0 Max100 Fallbackfalse

  • completed Whether the repondent finished the survey

    TypeBoolean

  • answers An array of all answers

    TypeArray[SurveyAnswer]

  • created_at Creation timestamp

    TypeString

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

    TypeString

  • question_id The id of the survey question

    TypeString

  • type The question type

    Typestring Enumnps,ces,csat,star,smileys,yesno,freeform,choice,ath_review_link

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

    TypeMixed

  • skip Whether the repondent skipped this question

    TypeBoolean

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