🡰 Back to overview 1.3 Documentation

Changelog Public REST API : 1.3

This document contains an overview of all changes made in the 1.3 version of the GuestXM public REST API

Oct 7, 2023

Behavior Changes

Extended Survey response details

  • 'source' Array of source values that was passed as part of prefill for a survey visitor (for example: pos order id, paytronix ticket id, etc)
  • Take Note: If none were passed this will default to an empty array
Apr 25, 2023

New features

Patch Survey Placeholders

  • Patch placeholders for a specific survey by passing a kv-map with the updated placeholder values
  • Only placeholders that exist within the survey can be updated
  • Only placeholders provided in the patch kv-map will be updated

global Webhook : INTEGRATION:CONNECTED

Receive a webhook notification when an integration is connected to a location

Behavior Changes

Extended Survey details

  • 'placeholders' KV-map of configured placeholders for a specific survey
  • Take Note: Available on both the single and list retrieval endpoints for surveys
Jul 12, 2022

New features

Single Feed Item Import

Import a single feed item into the GuestXM Inbox and insights

global Webhook : COMPANY:UPDATED

Receive a webhook notification when a company's meta information is updated

Apr 13, 2022

New features

Retrieve Surveys Answers

Retrieve a list of survey responses for a specific survey

Mar 23, 2022

New features

Retrieve Surveys

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

Behavior Changes

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
Feb 22, 2022

Behavior Changes

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 GuestXM tags that were added to a feed to the output for all Feed-retrieval endpoints (Best Reviews, All Reviews)
  • Take Note: If no tags were applied to a feed, it will contain an empty tags array
Feb 8, 2022

Behavior Changes

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
Dec 2, 2021

Behavior Changes

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
Nov 8, 2021

New features

Feed Reviews All Endpoint: Companywide

  • Retrieve a paginated list of reviews for an GuestXM 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 GuestXM 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 GuestXM 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
Sep 1, 2021

New features

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, instagram, tripadvisor, google_mybusiness, eetnu, booking, takeaway, foursquare
Aug 23, 2021

New features

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
Jul 23, 2021

Behavior Changes

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
Jul 4, 2021

New features

Feed Bulk Upload

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

global Webhook : FEED:UPLOAD:STARTED

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

global Webhook : FEED:UPLOAD:FINISHED

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

Jun 13, 2021

New features

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

May 11, 2021

New features

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

Behavior Changes

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).
Apr 10, 2021

New features

Retrieve best reviews

Retrieve a list of best reviews for a list of locations

Mar 28, 2021

Behavior Changes

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
Feb 28, 2020

New features

Retrieve best reviews

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

Behavior Changes

Extended Company details - Score

  • 'score' is now part of the company model, this is the last known GXM 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 GXM 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