Changelog Public REST API : 1.3

Retrieve Surveys Answers

Retrieve a list of survey responses for a specific survey

Retrieve Surveys

• Retrieve a list of live surveys for a company
• Retrieve the details of a specific survey

Extended Company details

• 'created_at' UTC creation timestamp of company
• Take Note: Available on both the single and list retrieval endpoints for companies

Extended Location details

• 'created_at' UTC creation timestamp of location
• Take Note: Available on both the single and list retrieval endpoints for locations

Extended NPS Insights - Distribution

• We have added nps distribution (promotors, passives, detractors) to the output for all nps-related insights endpoints.
• 'pos' denotes the amount of promotors
• 'neu' denotes the amount of passives
• 'det' denotes the amount of detractors
• Take Note: These new additions also work with average/cumulative data_fn props and any existing filter

Extended Score Insights - Distribution

• We have added score distribution (1-5 scale, with 1 being lowest and 5 being highest) to the output for all score-related insights endpoints.
• 'r1' denotes the amount of feedback items that would be a 1 on a 1-5 scale
• 'r2' denotes the amount of feedback items that would be a 2 on a 1-5 scale
• 'r3' denotes the amount of feedback items that would be a 3 on a 1-5 scale
• 'r4' denotes the amount of feedback items that would be a 4 on a 1-5 scale
• 'r5' denotes the amount of feedback items that would be a 5 on a 1-5 scale
• Take Note: These new additions also work with average/cumulative data_fn props and any existing filter

Extended Feed Details - Tags

• We have added AreTheyHappy tags that were added to a feed to the output for all Feed-retrieval endpoints (Best Reviews, Sampled Reviews, All Reviews)
• Take Note: If no tags were applied to a feed, it will contain an empty tags array

Extended Location Address details

• 'region' Where set this will contain the top-level sub-national administrative feature. Examples are provinces and states
• 'district' Where set this will contain an additional (non top-level) sub-national administrative feature such as prefectures in China.
• Take Note: Region and district will not always be set, if no value was found they will default to false

Extended Insights - Group By

• Insights can now be grouped by quarter as well
• This change has effect on all score and nps endpoints in both average and cumulative mode

Feed Reviews All Endpoint: Companywide

• Retrieve a paginated list of reviews for an AreTheyHappy company
• Take Note: Reviews returned will be limited to the last 6 months
• Take Note: Pagination is done by 50 reviews per page
• Take Note: Access to this endpoint is granted on a per client basis

Feed Reviews All Endpoint: Location-specific

• Retrieve a paginated list of reviews for an AreTheyHappy location
• Take Note: Reviews returned will be limited to the last 6 months
• Take Note: Pagination is done by 50 reviews per page
• Take Note: Access to this endpoint is granted on a per client basis

Extended Review Filtering

• 'no_trunc' has been added as a filter parameter to all review retrieval endpoints, default behavior remains to truncate at 512 characters, but passing no_trunc=1 will now turn off text truncation
• 'allow_private' has been added as a filter parameter to all review retrieval endpoints, default behavior remains to not return private reviews, but passing allow_private=1 will now also return private reviews

Extended Review details

• 'ath_id' is now part of the review model, this is a hashed review id that can be used for uniqueness checks when retrieving reviews through the public api
• 'location_ids' is now part of the review model, this is an array of one or more AreTheyHappy location ids that this review belongs to
• 'is_private' is now part of the review model, this denotes whether or not a review can be shown publicly
• 'is_truncated' is now part of the review model, this denotes whether or not a review was truncated
• 'is_empty' is now part of the review model, this denotes whether or not a review has any form of content whatsoever
• 'lang' is now part of the review model, this denotes an ISO 639 language code

Extended Location details - Connections

• 'connections' is now part of the location model, this is a KV map of connected channels on a location with their publicly available pages
• Each connected channel in the kv map is an object with a 'url_page' (Public profile link) and 'url_feedback' (Write a review link), either of these could be false if not available, please ensure to handle this case appropriately. Suggestion: In most cases the 'url_page' will always be available, we suggest falling back to this when using the 'url_feedback' property
• This change has effect on the location list and single location endpoints
• Take Note: url_page will fallback to false if there is no known public profile link
• Take Note: url_feedback will fallback to false if there is no known public 'write a review' link
• Take Note: This field only includes data for the following integration types - facebook, twitter, instagram, yelp, tripadvisor, google_mybusiness, eetnu, booking, takeaway, foursquare

Extended Location details - Alias

• 'alias' is now part of the location model, this is a string field that if set should be used in customer-accessible interfaces as an override of the location name
• This change has effect on the location list and single location endpoints
• Take Note: Alias will fallback to false if not configured

Extended Insights - Range

• Insights can now be retrieved as far as 5 years into the past (prior versions this was 1 year)
• This change has effect on all score and nps endpoints in both average and cumulative mode
• Take Note: The difference between start and end date can not be more than 366 days

Feed Bulk Upload

• Upload a data file and automatically have its contents serialized and inserted into the AreTheyHappy Inbox and insights
• Subscribe to webhooks to know exactly when your data file starts processing and when it's finished

global Webhook : FEED:BULK_UPLOAD:STARTED

Receive a webhook notification when a bulk upload job has started (job_id will be part of payload)

global Webhook : FEED:BULK_UPLOAD:FINISHED

Receive a webhook notification when a bulk upload job has finished (job_id will be part of payload)

global Webhook : COMPANY:INSIGHTS:UPDATED

Receive a webhook notification when a company's insights (score/nps) has been updated

global Webhook : LOCATION:INSIGHTS:UPDATED

Receive a webhook notification when a location's insights (score/nps) has been updated

Extended Score Insights

• 'amt' is now part of score insights. This is the amount of feedback items (such as reviews) that the score is based on
• This change has effect on all score endpoints in both average and cumulative mode

Extended NPS Insights

• 'amt' is now part of nps insights. This is the amount of feedback items (such as reviews) that the nps score is based on
• This change has effect on all nps endpoints in both average and cumulative mode

Extended Insights - Empty slots (_f)

• '_f': A new property on periodic insights which denotes that a specific group object in an array of grouped periodic insights is a blank/filler record
• Why? When requesting a period of insights we automatically fill in blank parts of a period. This ensures that a period's data structure is always pristine.
• Eg: Let's say you fetch all of 2020 and group by month, we will have a record for each month in the return dataset (regardless of whether that month has data).

Authorize

• Generate a user authentication token to the ATH platform, useful for Single Sign On (SSO)
• Take Note: Access to this endpoint is granted on a per client basis

Retrieve best reviews

Retrieve a list of best reviews for a list of locations

Retrieve sampled reviews

• Retrieve a sampled list of mixed reviews for a company
• Retrieve a sampled list of mixed reviews for a list of locations
• Retrieve a sampled list of mixed reviews for a specific location

Extended location details - Opening Hours

• 'opening_hours' is now part of the location model
• This change has effect on the location list and single location endpoints
• Take Note: Opening hours will fallback to false if there are no opening hours configured

Retrieve best reviews

• Retrieve a list of best reviews for a company
• Retrieve a list of best reviews for a specific location

Extended Company details - Score

• 'score' is now part of the company model, this is the last known ATH score for that company
• This change has effect on the company list and single company endpoints
• Take Note: Score will fallback to false if there is no last known score

Extended Location details - Score

• 'score' is now part of the location model, this is the last known ATH score for that location
• This change has effect on the location list and single location endpoints
• Take Note: Score will fallback to false if there is no last known score