Public REST API : 1.3

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

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

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"
}

GET /company/{company_id}/locations

Lists all locations for a company

Parameters

path company_id: Id of the company

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://..."
            },
            "yelp": {
                "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
path location_id: Id of the location

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://..."
        },
        "yelp": {
            "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
query group_by: Group the result set
query start: Start date, can't be older than 5 years
query end: End date, can't be today, in the future or before start
query data_fn: Switch between cumulative and average NPS
query location_ids: Comma delimited string of location ids that aggregate NPS need to be retrieved for

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
path location_id: Id of the location
query group_by: Group the result set
query start: Start date, can't be older than 5 years
query end: End date, can't be today, in the future or before start
query data_fn: Switch between cumulative and average NPS

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
query group_by: Group the result set
query start: Start date, can't be older than 5 years
query end: End date, can't be today, in the future or before start
query data_fn: Switch between cumulative and average score
query location_ids: Comma delimited string of location ids that aggregate scores need to be retrieved for

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
path location_id: Id of the location
query group_by: Group the result set
query start: Start date, can't be older than 5 years
query end: End date, can't be today, in the future or before start
query data_fn: Switch between cumulative and average score

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
query location_ids: Comma delimited string of location ids for this company to retrieve reviews for
query integrations: Comma delimited string of integrations to pull reviews for
query page_nr: The page number
query allow_empty: Whether or not reviews that are empty or below 10 characters should be returned
query allow_private: Whether or not private reviews should be returned
query no_trunc: Whether or not truncation should happen

Response codes

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

Example response

{
    "count": 2,
    "reviews": [
        {
            "ath_id": "de13234...",
            "location_ids": [
                120591
            ],
            "integration_type": "google_mybusiness",
            "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
query location_ids: Comma delimited string of location ids for this company to retrieve reviews for
query integrations: Comma delimited string of integrations to pull best reviews for
query limit: The amount of reviews to be returned
query allow_empty: Whether or not reviews that are empty or below 10 characters should be returned
query allow_private: Whether or not private reviews should be returned
query no_trunc: Whether or not truncation should happen

Response codes

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

Example response

{
    "count": 2,
    "reviews": [
        {
            "ath_id": "de13234...",
            "location_ids": [
                120591
            ],
            "integration_type": "google_mybusiness",
            "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 GuestXM 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 GuestXM support as they are customized to the data payload you are providing.

Parameters

path company_id: Id of the company
body location_id: Id of the location
body template_id: Id of the GuestXM template to use for parsing the contents
body payload: Payload for the inbox feed item, content depends on the template the template_id is linked to

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 GuestXM 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
Currently we only support CSV files
Template Ids are provided by GuestXM 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:UPLOAD:STARTED webhook is sent out
On job finish: A FEED:UPLOAD:FINISHED webhook is sent out containing some additional results

Parameters

path company_id: Id of the company
body file_url: URL for externally hosted file to be uploaded
body template_id: Id of the GuestXM template to use for parsing the contents
body mapping: Array of objects with mapping of location to identifier in the file, passed as a JSON string or JSON array

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
path location_id: Id of the location
query integrations: Comma delimited string of integrations to pull reviews for
query page_nr: The page number
query allow_empty: Whether or not reviews that are empty or below 10 characters should be returned
query allow_private: Whether or not private reviews should be returned
query no_trunc: Whether or not truncation should happen

Response codes

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

Example response

{
    "count": 2,
    "reviews": [
        {
            "ath_id": "de13234...",
            "location_ids": [
                120591
            ],
            "integration_type": "google_mybusiness",
            "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
path location_id: Id of the location
query integrations: Comma delimited string of integrations to pull best reviews for
query limit: The amount of reviews to be returned
query allow_empty: Whether or not reviews that are empty or below 10 characters should be returned
query allow_private: Whether or not private reviews should be returned
query no_trunc: Whether or not truncation should happen

Response codes

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

Example response

{
    "count": 2,
    "reviews": [
        {
            "ath_id": "de13234...",
            "location_ids": [
                120591
            ],
            "integration_type": "google_mybusiness",
            "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

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": "GuestXM Welcome Survey",
        "public_description": "Welcome to GuestXM, 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
        },
        "placeholders": {
            "promoCode": 125964
        },
        "created_at": "2020-02-16 14:23:24.000Z"
    },
    {
        "id": "cf134...",
        "name": "Post-Dinner Survey",
        "url": "https://areyouhappy.com/...",
        "public_title": "GuestXM 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
        },
        "placeholders": {
            "promoCode": 973214
        },
        "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
path survey_id: Id of the survey

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": "GuestXM Welcome Survey",
    "public_description": "Welcome to GuestXM, 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
    },
    "placeholders": {
        "promoCode": 125964
    },
    "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
path survey_id: Id of the survey
query location_ids: Comma delimited string of location ids for this company to retrieve reviews for
query page_nr: The page number
query start: Start date, can't be older than 6 months
query has_consent: Whether the respondent gave consent

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,
            "source": [],
            "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,
            "source": [
                {
                    "val": "81b0fa52-4bf4-42f9-9e6d-27552df2c582"
                }
            ],
            "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"
        }
    ]
}

PATCH /company/{company_id}/surveys/{survey_id}/placeholders

Updates survey placeholders by survey's 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
path survey_id: Id of the survey
body placeholders: Survey placeholders object

Response codes

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

Example response

{
    "survey_id": "cf134"
}

Models

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

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, instagram, 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://..."
        },
        "yelp": {
            "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, instagram, 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 GuestXM Location Ids

TypeArray[Integer]
integration_type The type of integration this came from

Typestring Enumfacebook,tripadvisor,google_mybusiness,formitable,tablemanager,eetnu,zomato,resengo,manual_review,takeaway,booking,ifood,deliveroo,uber_eats,paytronix,thanx
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 GuestXM 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 GuestXM 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 GuestXM Location to map to

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

TypeString

Example

[
    {
        "id": 1,
        "name": "GuestXM - Ghent"
    },
    {
        "id": 2,
        "name": "GuestXM - 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": "GuestXM Welcome Survey",
    "public_description": "Welcome to GuestXM, 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
    },
    "placeholders": {
        "promoCode": 125964
    },
    "created_at": "2020-02-16 14:23:24.000Z"
}

Survey Response

id Hashed id of the survey response

TypeString
location_id GuestXM 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
source Array of source ids for external systems passed as part of prefill to a survey visitor, eg: (pos order id, paytronix ticket id)

TypeArray
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,
    "source": [
        {
            "val": "81b0fa52-4bf4-42f9-9e6d-27552df2c582"
        }
    ],
    "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,date,smileys,yesno,freeform,choice,ath_review_link,unique_id
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
}

Survey Placeholders Patch Object

Notes

The object provided is a key-value map where keys represent the names of the placeholders you want to update and the values are the values you wish to give them
Placeholders need to exist on a survey before you can update them through the public api

Example

{
    "placeholders": {
        "promoCode": "123456",
        "campaignTitle": "Burgerpalooza"
    }
}

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: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