This document provides a global overview of the GuestXM Public API and how it operates. To view version-specific documentation regarding endpoints and models use the approriate version links in the section titled "API Versions".
Are you an GuestXM customer or integration partner who doesn't have access yet to the GuestXM public API? Please send us an e-mail at [email protected] explaining your use case and we'll get back to you asap.
The GuestXM Public API is a versioned API that uses semver major/minor as its foundation. This means that all versions within the same minor number are always backwards compatible with each other (eg: 1.3 will be fully backwards compatible with 1.2, which in turn will be backwards compatible with 1.1).
Changes in a major version (eg: 2.0 vs 1.3) will mean a breaking change between versions that are not backwards compatible.
We make additions/improvements to the public API on a periodic basis, all changes will be noted down in the changelog for that version with the date of addition.
Authentication is done by providing your api key in the header of the requests.
An api key is linked to a specific app and environment, it needs to be requested through [email protected]. When the api client has been approved and created we will send you your authentication key.
There are 2 environments of the GuestXM public api, a staging (for testing purposes) and a production environment (live). Each environment will have its own api key.
If you need access to a testing account on our staging environment, please contact [email protected] and we'll get back to you asap.
The response format is application/json and every response is wrapped in the following structure:
{
"data" : {},
"meta" : {},
"warnings" : {}
}This structure was chosen with a purpose to allow for more detailed data scenarios to be easily parsed on both front/backend.
Please find a description of these 3 categories below:
{
"data" : {
"id": 123456789,
"name": "Acme Corp",
},
"meta" : {},
"warnings" : {}
}{
"data": {
"status": 404,
"detail": "The requested resource could not be found"
},
"meta": {},
"warnings": {}
}{
"data": {
"status": 400,
"detail": "Bad request"
},
"meta": {
"code": "ERR:MSG:VALIDATION:START_FORMAT"
},
"warnings": {}
}The GuestXM Public API applies rate limiting on almost every endpoint (endpoints that are excempt from this rule will have this mentioned in their documentation).
There are 3 forms of rate limitting to be aware of:
When your daily rate limit has been used up, the GuestXM Public API will respond with a "429 Too Many Requests" response code
{
"data": {
"status": 429,
"detail": "Too many requests"
},
"meta" : {
"code": "ERR:MSG:RATELIMITTED",
},
"warnings" : {
"limits": {
"reads": 2500,
"writes": 500
},
"current": {
"reads": 2501,
"writes": 100
}
}
}{
"data": {
"status": 429,
"detail": "Too many requests"
},
"meta" : {
"code": "ERR:MSG:QUOTA_REACHED",
},
"warnings" : {
"name": "bulk_upload",
"used": 11,
"quota": 10
}
}Each client api key can be configured for webhook requests. If configured, webhook requests will be sent as POST requests to the endpoint of your choice. Below you can find the list of all possible webhook events that we fire off:
{
"data" : {
"sent_at": 1564662600,
"action": "LOCATION:CREATED",
"payload": {
"company_id": 999999,
...
}
},
"meta" : {},
"warnings" : {}
}Please use the below table to fully understand the structure of our webhook events:
If a webhook secret is configured, this secret will be sent along in the headers of the webhook request as the X-GXM-APISIGNATURE. The signature will be the configured secret hashed with SHA256
Example: Secret123456789 becomes:
Configuration for webhooks needs to be requested through [email protected]