NAV Navbar
json

Introduction

Welcome to the Guesty platform API!

Each feature is designed to help our users more easily make changes on Guesty's system while ensuring the best service experience.

This article on our Help Center details the recent changes and is designed to keep you continuously informed on any additions or updates to our API and API documentation.

To receive the latest updates on this topic directly to your email, subscribe to this post by clicking "follow our updates" at the bottom.

Default Base URL

The default base URL for Guesty API is: https://api.guesty.com/api/v2/
All data should be sent in JSON format and with a Content-Type: application/json header.

Note: for security reasons, all Guesty APIs are served over HTTPS only.

Authentication

To use the Guesty API, you’ll need a private API key that is linked to your account. Creating both tokens is possible through the Guesty Dashboard.
You can learn how to generate a Basic one here
Partners can use the Bearer authentication found in our Marketplace.
Be sure to keep this API key private. All API requests must be made over HTTPS and are authenticated via HTTP Basic Auth. Use your API key as the username and secret as the password.

Search

Search for everything

  [
        {
            "type": "reservation",
            "_id": "537266ab8cc22c0b000000b7",
            "title": "Booking #ABCDEF",
            "description": "Koby Soto on dates Oct. 28 - Nov. 01",
            "picture": "http://images.com/image.jpg"
        }
    ]

HTTP Request

GET /search

Query Parameters

Parameter Default Description Example
q null Required Search query string. Koby Soto
type null Limit search subjects. No limit when null. Options are accounts, users, contacts, owners, integrations, listings, bookings, views. users
limit 25 Pagination, max: 100 25
skip 0 Pagination 0

Users can be found using fullName, emails, phones properties.

Integrations can be found using the nickname, externalLink, incomingEmail properties.

Contacts can be found using the fullName, emails, phones properties.

Owners can be found using fullName, email properties.

Listings can be found using the title, nickname, tags, address.full, integrations.externalUrl properties.

Bookings can be found using the confirmationCode, guest.fullName, guest.emails, guest.phones properties.

Views can be found using the title property.

Response

Attribute Description
type Result type. Options are account, user, contact, owner, integration, listing, reservation
_id The result unique id in its collection, for instance, for users, users._id
title The title to display. For accounts: name; For users: fullName; For contacts: fullName; For integrations: fullName; For listings: title; For bookings: Booking #confirmationCode; For views: title.
description The description to display. For users: email, phone; For contacts: email, phone; For integrations: nickname, incomingEmail; For listings: address.full; For bookings: guest.fullname on dates checkIn-checkOut
picture The picture to display. For users: picture.thumbnail; For contacts: null; For listings: picture.thumbnail; For bookings: guest.picture.thumbnail
nickname For listings: nickname; For all others: null

NOTE: When searching an email address that includes (+) for example: israel+israeli@gmail.com, the proper way to search it, is to remove the (+) and add space instead. My search query will be: israel israeli

Accounts

The account object

{
    "_id": "596f6fe706112710005d96ff",
    "active": true,
    "ignoredHooks": [],
    "pms": {
        "cleaningStatus": {
            "statusFade": {
                "active": true,
                "days": 5,
                "toStatus": "unknown"
            },
            "markAsDirtyOnCheckIn": true
        },
        "calendar": {
            "requireReasonForUpdatingPricing": true
        },
        "website": {
            "defaultStatusForNewReservations": "inquiry",
            "defaultSort": "title",
            "includedListings": [],
            "excludedListings": []
        },
        "paymentProcessing": {
            "paymentProviders": {
                "stripe": {
                    "active": true,
                    "status": "ACTIVE",
                    "accountName": "Guesty Inc.",
                    "defaultCurrency": "usd",
                    "syncedAt": "2019-11-20T21:31:01.109Z",
                    "payload": {
                        "livemode": true,
                        "token_type": "bearer",
                        "stripe_publishable_key": "pk_live_Rh6dRWYPSXeVPPCjsLFB6Ezq008sT1fCHJ",
                        "stripe_user_id": "acct_19nmQxLYcJ0oiNhY",
                        "scope": "read_write",
                        "id": "acct_19nmQxLYcJ0oiNhY"
                    }
                }
            },
            "active": true
        }
    },
    "whiteLabel": {
        "integrationEmailDomains": [],
        "shouldWhiteLabelApp": true
    },
    "__v": 43855,
    "hadFirstBookingAt": "2017-07-23T10:40:20.040Z",
    "initialLocation": "",
    "currency": "USD",
    "availablePhoneNumbers": [],
    "pricePlanMinimum": 3,
    "companyLogo": "https://cdn.filepicker.io/api/file/SRNViTfRb2RVqW3nWQbw",
    "internalData": {
        "agreedToTOS": {
            "lastName": "Simpson",
            "firstName": "OJ",
            "userEmail": "canttouchthis@dananana.canttouchthis",
            "date": "2017-07-23T16:04:43.772Z"
        },
        "features": {
            "airbnbIntegration": "BOTH"
        },
        "oldOnboardingStatus": "Opted out",
        "accountManager": null,
        "onboardingStatus": "Opted out"
    },
    "customFields": [
        {
            "options": [],
            "_id": "5bcebe5803e62d01859831dc",
            "displayName": "xs",
            "isPublic": false,
            "key": "xs",
            "object": "reservation",
            "type": "boolean"
        },
        {
            "options": [],
            "_id": "5974a9ac8331fb0f00ab26b0",
            "object": "reservation",
            "type": "boolean",
            "isPublic": true,
            "key": "Personal check in?",
            "displayName": "personalcheckin"
        },
        {
            "options": [
                "5",
                "34",
                "555"
            ],
            "_id": "5a899f7faa58810025b3f213",
            "object": "reservation",
            "type": "enum",
            "isPublic": true,
            "key": "Rachel test",
            "displayName": "racheltest"
        },
        {
            "options": [],
            "_id": "5a8e8dd6c2f9cc009add7438",
            "object": "reservation",
            "type": "number",
            "isPublic": true,
            "key": "ReservationValue",
            "displayName": "reservationvalue"
        }
    ],
    "initialReferrer": "",
    "receptionistsService": {
        "receptionDesk": {
            "ittt": []
        },
        "screening": {
            "checklist": []
        },
        "contactPersonUserId": null
    },
    "createdAt": "2017-07-19T14:42:47.162Z",
    "signupQuestions": [],
    "billing": {
        "billingCycle": "Weekly",
        "billingDay": 1,
        "nextBillingDate": "2017-07-19T14:42:47.165Z",
        "paymentMethods": [],
        "noFreezingFlow": true,
        "stripeCustomerId": "cus_B3jQEYNMH9zRxr"
    },
    "plan": [
        {
            "_id": "5974a99ac5cde90f0012d9d6",
            "name": "SOFTWARE",
            "planType": "RESERVATION_COMMISSION",
            "value": 15,
            "isLocked": true
        },
        {
            "_id": "5974a99ac5cde90f0012d9d5",
            "value": 2,
            "isLocked": true,
            "name": "RECEPTIONISTS_SERVICE",
            "planType": "RESERVATION_COMMISSION"
        },
        {
            "_id": "5974a99ac5cde90f0012d9d4",
            "name": "RENTALS_UNITED",
            "planType": "RESERVATION_COMMISSION",
            "isLocked": true
        },
        {
            "_id": "5974a99ac5cde90f0012d9d3",
            "planType": "RESERVATION_COMMISSION",
            "isLocked": true,
            "name": "AIRBNB"
        },
        {
            "_id": "5974a99ac5cde90f0012d9d2",
            "isLocked": true,
            "name": "WEBSITE",
            "planType": "ACCOUNT_MONTHLY"
        },
        {
            "_id": "5974a99ac5cde90f0012d9d1",
            "name": "API_ACCESS",
            "planType": "ACCOUNT_MONTHLY",
            "isLocked": true
        },
        {
            "_id": "5974a99ac5cde90f0012d9d0",
            "name": "PAYMENT_PROCESSING",
            "planType": "TRANSACTION_COMMISSION",
            "isLocked": true,
            "value": 0
        },
        {
            "_id": "5974a99ac5cde90f0012d9cf",
            "name": "WHITE_LABELING",
            "planType": "ACCOUNT_MONTHLY",
            "isLocked": true
        }
    ],
    "accountCategorization": 5,
    "onBoarding": {
        "createdFirstHookAt": "2017-07-23T12:50:00.330Z",
        "zendeskTicketId": "129605"
    },
    "activatedAt": "2017-07-23T10:18:41.781Z",
    "apiKeys": [ ],
    "systemEmailsRecipients": [
        "5b3222833122510103150bc4"
    ],
    "name": "Guesty",
    "commissionTaxPercentage": 15,
    "taxes": [
        {
            "_id": "5d2883fcc2d81b001f06f55e",
            "name": "",
            "type": "LOCAL_TAX",
            "units": "FIXED",
            "quantifier": "PER_STAY",
            "amount": 2
        },
        {
            "_id": "5df61e77f7e612001f80fabc",
            "name": "",
            "type": "CITY_TAX",
            "units": "FIXED",
            "quantifier": "PER_GUEST_PER_NIGHT",
            "amount": 5.5
        }
    ],
    "RUFeeActivation": true,
    "mailingAddress": {
        "lat": 30.7807867,
        "lng": -95.4593714,
        "full": "Arizona Ln, Huntsville, TX 77320, USA"
    },
    "agodaEmail": "agoda@guesty.com",
    "accountCategorizationIsManual": true,
    "markups": {
        "agoda": {
            "amount": 100,
            "units": "PERCENTAGE",
            "status": "MANUALLY_ALTERED"
        },
        "default": {
            "units": "PERCENTAGE",
            "amount": null
        },
        "bookingCom": {
            "amount": 20,
            "units": "PERCENTAGE",
            "status": "MANUALLY_ALTERED"
        },
        "manual": {
            "status": "MANUALLY_ALTERED",
            "units": "PERCENTAGE",
            "amount": 3
        },
        "airbnb": {
            "amount": 6,
            "units": "PERCENTAGE",
            "status": "MANUALLY_ALTERED"
        },
        "homeaway2": {
            "amount": 8.5,
            "units": "PERCENTAGE",
            "status": "MANUALLY_ALTERED"
        }
    },
    "financials": {
        "channelCommission": {
            "rentalsUnited": {
                "bookingCom": {
                    "tax": 1
                },
                "expedia": {
                    "commission": {
                        "value": 0,
                        "of": [
                            "fareAccommodation",
                            "fareCleaning"
                        ]
                    },
                    "tax": 0
                },
                "agoda": {
                    "commission": {
                        "value": 5,
                        "of": [
                            "fareAccommodation"
                        ]
                    },
                    "tax": 1
                }
            },
            "useAccountSettings": true,
            "_id": "5b41cd9ecfe09b002596e132",
            "bookingCom": {
                "tax": 7
            },
            "homeaway2": {
                "tax": 0,
                "commission": {
                    "value": 0,
                    "of": [
                        "fareAccommodation",
                        "fareCleaning"
                    ]
                }
            }
        }
    },
    "commissionFormula": "net_income*0.2",
    "netIncomeFormula": "fare_accommodation + fare_cleaning",
    "ownerRevenueFormula": "net_income*0.3",
    "cancellationSurvey": [
        {
            "date": "2018-11-04T14:40:18.967Z",
            "_id": "5bdf04d2445079003767abab",
            "subReasons": {
                "Other": {
                    "Other": "selected",
                    "OtherInput": "PLEASE IGNORE - This is a test.\n\nKevin verifying the cancellation flow."
                }
            },
            "reasons": {
                "Onboarding experience": "hidden",
                "Missing features": "unselected",
                "Technical issues": "unselected",
                "System usability": "unselected",
                "Value for money": "unselected",
                "Customer support": "unselected",
                "Guest Communication Service": "unselected",
                "Other": "selected"
            }
        },
        {
            "date": "2018-11-28T06:48:49.011Z",
            "_id": "5bfe3a51c62cd50037d06454",
            "subReasons": {
                "Other": {
                    "Other": "selected",
                    "OtherInput": "Just another test by Kevin, Please ignore."
                }
            },
            "reasons": {
                "Onboarding experience": "hidden",
                "Missing features": "unselected",
                "Technical issues": "unselected",
                "System usability": "unselected",
                "Value for money": "unselected",
                "Customer support": "unselected",
                "Guest Communication Service": "unselected",
                "Other": "selected"
            }
        },
        {
            "date": "2018-11-28T06:50:13.503Z",
            "_id": "5bfe3aa5d8ac95003cef6e66",
            "subReasons": {
                "Other": {
                    "Other": "selected",
                    "OtherInput": "Another test by kevin. Sorry."
                }
            },
            "reasons": {
                "Onboarding experience": "hidden",
                "Missing features": "unselected",
                "Technical issues": "unselected",
                "System usability": "unselected",
                "Value for money": "unselected",
                "Customer support": "unselected",
                "Guest Communication Service": "unselected",
                "Other": "selected"
            }
        }
    ],
    "timezone": "Asia/Jerusalem",
    "companyInformation": {
        "_id": "5c2cc1151915150028b6ec2d",
        "contactFirstname": "qa qa",
        "contactEmail": "qa@guesty.com",
        "name": "Guesty",
        "businessType": "INDIVIDUAL",
        "vatNum": "123456",
        "country": "IL",
        "address": "Eliezar Kaplan 2",
        "city": "Tel Aviv",
        "zipCode": "8997447",
        "contactLastname": "QA",
        "contactPhone": "+972501234567",
        "corporationPlace": "IL",
        "submittedAt": "2019-06-05T09:01:42.399Z"
    },
    "weekendBasePriceMigrationDone": true,
    "sisenseAccess": true,
    "pricePlanMaximum": null,
    "recognizedRevenueMode": "check-in",
    "migration": {
        "rateStrategy": "2019-08-13T09:13:35.194Z"
    },
    "statementDescriptor": ""
}
Attribute Type Description
_id String Unique id
accountId String Unique id
name String
email String Account email
active Boolean
mailgun Object
isInterestedInServiceOnExistingReservations Boolean
signupQuestions [Object]
recognizedRevenueMode [Object]
ignoredHooks [Object]
initialLocation String
recognizedRevenueDays Number
initialReferrer String
--_id String Unique id
--question String
--answer String
mailingAddress Object
---lat Number
---lng Number
---full String
sisenseAccess Boolean
recognizedRevenueMode Enum ['check-in', 'check-out', 'per_night'],
companyInformation Mixed
createdAt Date
cancellationSurvey [Object]
RUFeeActivation Boolean
timezone String
currency String
companyLogo String
accountCategorization Number
accountCategorizationIsManual Boolean
agodaEmail String
onBoarding Object
plan [Object]
migration [Object]
---rateStrategy Date
pricePlanMinimum Number
pricePlanMaximum Number
SaaS Object
billing Object
freezingFlow Object
availablePhoneNumbers [String] Phone numbers that the user has bought
proxyEmail String
whiteLabel Object
---shouldWhiteLabelApp Boolean
---brand Object
------name String
------picture String
---appDomain String
---integrationEmailDomains [Object]
------domain String
------smtp Object
---------user String
---------pass String
---integrationsEmailDomain String
systemEmailsRecipients [String] User IDs
receptionistsService Object
---contactPersonUserId String User ID
---receptionDesk Object
------ittt [Object]
---------ifThis String
---------thenThat String
------whiteLabel Boolean
------customImpersonation String
------customSignature String
---screening Object
------checklist [Object]
---------item String
---------isProactive Boolean
postBookingService Object
---manualWorkDescription String
pms Object
---inbox Object
------customSignature String
---cleaningStatus Object
------statusFade Object
---------active Boolean
---------days Number
---------toStatus Enum ['unknown', 'dirty']
------markAsDirtyOnCheckIn Boolean
---calendar Object
------requireReasonForUpdatingAvailability Boolean
------requireReasonForUpdatingPricing Boolean
---paymentProcessing Object
------active Boolean
------paymentProviders: Object
---------stripe Object
------------active Boolean
------------status String ADD EXAMPLES
------------accountName String
------------defaultCurrency String
------------syncedAt Date
------------payload Enum
apiKeys [Object]
---key String
---secret String
---label String
ownerRevenueFormula String
netIncomeFormula String
commissionFormula String
commissionTaxPercentage Number [0-100]
financials Object
---channelCommission Object
taxes [Object]
internalData Object
markups [Object]
customFields Object
---_id String Unique id
---object Enum ['listing', 'reservation']
---key String Custom field name
---displayName String Custom display name
---type Enum ['text', 'longtext', 'number', 'date', 'time', 'boolean', 'user', 'contact', 'enum']
---options [String] For Enum custom fields
---isPublic Boolean

Retrieve account object

{
    "_id": "596f6fe706112710005d96ff",
    "active": true,
    "ignoredHooks": [],
    "pms": {
        "cleaningStatus": {
            "statusFade": {
                "active": true,
                "days": 5,
                "toStatus": "unknown"
            },
            "markAsDirtyOnCheckIn": true
        },
        "calendar": {
            "requireReasonForUpdatingPricing": true
        },
        "website": {
            "defaultStatusForNewReservations": "inquiry",
            "defaultSort": "title",
            "includedListings": [],
            "excludedListings": []
        },
        "paymentProcessing": {
            "paymentProviders": {
                "stripe": {
                    "active": true,
                    "status": "ACTIVE",
                    "accountName": "Guesty Inc.",
                    "defaultCurrency": "usd",
                    "syncedAt": "2019-11-20T21:31:01.109Z",
                    "payload": {
                        "livemode": true,
                        "token_type": "bearer",
                        "stripe_publishable_key": "pk_live_TOKEN",
                        "stripe_user_id": "acct_19nmQxLYcJ0oiNhY",
                        "scope": "read_write",
                        "id": "acct_19nmQxLYcJ0oiNhY"
                    }
                }
            },
            "active": true
        }
    },
    "whiteLabel": {
        "integrationEmailDomains": [],
        "shouldWhiteLabelApp": true
    },
    "__v": 43802,
    "hadFirstBookingAt": "2017-07-23T10:40:20.040Z",
    "currency": "USD",
    "availablePhoneNumbers": [],
    "pricePlanMinimum": 3,
    "companyLogo": "https://cdn.filepicker.io/api/file/SRNViTfRb2RVqW3nWQbw",
    "customFields": [
        {
            "options": [],
            "_id": "5bcebe5803e62d01859831dc",
            "displayName": "xs",
            "isPublic": false,
            "key": "xs",
            "object": "reservation",
            "type": "boolean"
        }
    ],
    "receptionistsService": {
        "receptionDesk": {
            "ittt": []
        },
        "screening": {
            "checklist": []
        },
        "contactPersonUserId": null
    },
    "createdAt": "2017-07-19T14:42:47.162Z",
    "billing": {
        "billingCycle": "Weekly",
        "billingDay": 1,
        "nextBillingDate": "2017-07-19T14:42:47.165Z",
        "paymentMethods": [],
        "noFreezingFlow": true,
        "stripeCustomerId": "cus_B3jQEYNMH9zRxr"
    },
    "activatedAt": "2017-07-23T10:18:41.781Z",
    "apiKeys": [
        {
            "secret": "_id_dff1_123456",
            "label": "NAme",
            "_id": "5981b4b8c97c260f0067c499",
            "key": "803416249899a7c660efe45320adf8ba",
            "gateway_uid": "60842581-36a1-499f-8461-269599c0b160"
        }
    ],
    "systemEmailsRecipients": [
        "5b3222833122510103150bc4"
    ],
    "name": "Guesty QA",
    "commissionTaxPercentage": 15,
    "taxes": [
        {
            "_id": "5d2883fcc2d81b001f06f55e",
            "name": "",
            "type": "LOCAL_TAX",
            "units": "FIXED",
            "quantifier": "PER_STAY",
            "amount": 2
        },
        {
            "_id": "5df61e77f7e612001f80fabc",
            "name": "",
            "type": "CITY_TAX",
            "units": "FIXED",
            "quantifier": "PER_GUEST_PER_NIGHT",
            "amount": 5.5
        }
    ],
    "RUFeeActivation": true,
    "mailingAddress": {
        "lat": 34.0489281,
        "lng": -111.0937311,
        "full": "Arizona, USA"
    },
    "agodaEmail": "kjhlkjh@gmail.com",
    "markups": {
        "agoda": {
            "amount": 100,
            "units": "PERCENTAGE",
            "status": "MANUALLY_ALTERED"
        },
        "default": {
            "units": "PERCENTAGE",
            "amount": null
        },
        "bookingCom": {
            "amount": 20,
            "units": "PERCENTAGE",
            "status": "MANUALLY_ALTERED"
        },
        "manual": {
            "status": "MANUALLY_ALTERED",
            "units": "PERCENTAGE",
            "amount": 3
        },
        "airbnb": {
            "amount": 6,
            "units": "PERCENTAGE",
            "status": "MANUALLY_ALTERED"
        },
        "homeaway2": {
            "amount": 8.5,
            "units": "PERCENTAGE",
            "status": "MANUALLY_ALTERED"
        }
    },
    "financials": {
        "channelCommission": {
            "rentalsUnited": {
                "bookingCom": {
                    "tax": 1
                },
                "expedia": {
                    "commission": {
                        "value": 0,
                        "of": [
                            "fareAccommodation",
                            "fareCleaning"
                        ]
                    },
                    "tax": 0
                },
                "agoda": {
                    "commission": {
                        "value": 5,
                        "of": [
                            "fareAccommodation"
                        ]
                    },
                    "tax": 1
                }
            },
            "useAccountSettings": true,
            "_id": "5b41cd9ecfe09b002596e132",
            "bookingCom": {
                "tax": 4
            }
        }
    },
    "commissionFormula": "net_income*0.2",
    "netIncomeFormula": "fare_accommodation + fare_cleaning",
    "ownerRevenueFormula": "net_income*0.3",
    "cancellationSurvey": [
        {
            "date": "2018-11-04T14:40:18.967Z",
            "_id": "5bdf04d2445079003767abab",
            "subReasons": {
                "Other": {
                    "Other": "selected",
                    "OtherInput": "PLEASE IGNORE - This is a test.\n\nKevin verifying the cancellation flow."
                }
            },
            "reasons": {
                "Onboarding experience": "hidden",
                "Missing features": "unselected",
                "Technical issues": "unselected",
                "System usability": "unselected",
                "Value for money": "unselected",
                "Customer support": "unselected",
                "Guest Communication Service": "unselected",
                "Other": "selected"
            }
        }
    ],
    "timezone": "Asia/Jerusalem",
    "companyInformation": {
        "_id": "5c2cc1151915150028b6ec2d",
        "contactFirstname": "qa qa",
        "contactEmail": "qa@guesty.com",
        "name": "QA Guesty",
        "businessType": "INDIVIDUAL",
        "vatNum": "123456",
        "country": "IL",
        "address": "Eliezar Kaplan 2",
        "city": "Tel Aviv",
        "zipCode": "8997447",
        "contactLastname": "QA",
        "contactPhone": "+972501234567",
        "corporationPlace": "IL",
        "submittedAt": "2019-06-05T09:01:42.399Z"
    },
    "weekendBasePriceMigrationDone": true,
    "sisenseAccess": true,
    "pricePlanMaximum": null,
    "recognizedRevenueMode": "check-in",
    "migration": {
        "rateStrategy": "2019-08-13T09:13:35.194Z"
    }
}

HTTP Request

GET /accounts/me

Response

The requested account information.

Attribute Structure Description
_id String Unique id
active Boolean Status of connection
ignoredHooks [String]-(ObjectId)
pms Object (see below)
whiteLabel Boolean
hadFirstBookingAt Date
currency Enum
availablePhoneNumbers [String] Phone numbers that the user has bought
pricePlanMinimum Number
companyLogo String URL
customFields [Object] (see below)
receptionistsService Object (see below)
createdAt Date The date this account was created
billing Object
activatedAt Date The date this account was activated
apiKeys [Object] (see below)
systemEmailsRecipients [String]
name String
commissionTaxPercentage Number
taxes [Object]
RUFeeActivation Boolean
mailingAddress Object (see below)
agodaEmail String
markups Object
financials Object
commissionFormula String
netIncomeFormula String
ownerRevenueFormula String
cancellationSurvey [Object]
timezone String
companyInformation Object
weekendBasePriceMigrationDone Boolean
sisenseAccess Boolean
pricePlanMaximum Number
recognizedRevenueMode String
migration Object

The mailingAddress object

Attribute Type Description
state String The state of the mailing list
city String The city of the mailing list
address String The address of the mailing list
lat String The latitude of the mailing list
lng String The longitude of the mailing list
full String The full address of the mailing list
zipcode String The zipcode of the mailing list
country String The country of the mailing list

The apiKeys object

Attribute Type Description
_id String Unique id
secret String
label String
key String
gateway_uid String uid

The customFields object

Attribute Type Description
fieldId ObjectId Ref to the definition (account.customFields._id)
value Mixed Type is according to the definition

The pms object

{
    "active": true,
    "cleaningStatus": {
        "markAsDirtyOnCheckIn": true,
        "statusFade": {
            "active": true,
            "days": 15,
            "toStatus": "dirty"
        }
    },
    "autoPayments": {
        "policy": []
    },
    "tasks": {
        "defaultTasks": []
    },
    "automation": {}
}
Attribute Type Description
active Boolean
automation Object (see below)
inbox Object
---customSignature String
cleaningStatus Object
---active Boolean
---markAsDirtyOnCheckIn Boolean
---statusFade Object
------active Boolean
------days Number
------toStatus Enum unknown, dirty
paymentProcessing Object
---active Boolean
autoPayments Object
---policy [policy] (see below)

The automation object

{
    "autoList": {
        "config": [
            "101110111101011101101111",
            "110110111101111101111011",
            "110110101011011101101111",
            "110110111001011101101111",
            "101110111101010101111111",
            "111100111101011101101111",
            "111110111101011101101111"
        ],
        "active": true
    },
    "autoPricing": {
        "active": true,
        "rules": [
            {
                "startingFromDaysAhead": 4,
                "tillDaysAhead": 10,
                "amount": -10,
                "unit": "%",
                "subject": "available",
                "_id": "59aea8faf2fc8c9a00ac02f2",
                "condition": {
                    "amount": 3
                }
            }
        ]
    },
    "autoReviews": {
        "starRating": 5,
        "daysBeforeSending": 3,
        "active": true,
        "templates": [
            "example number one",
            "example number two"
        ]
    },
    "homeAutomation": {
        "buzzer": {
            "toDial": "2",
            "active": true,
            "incomingNumber": "97250404534"
        }
    },
    "calendarSmartRules": {
        "active": true,
        "blockListings": [
            "59a415396f6f010f0099b391"
        ]
    },
    "hooks": {
        "active": true,
        "ignoredHooks": []
    },
    "answeringMachine": {
        "active": true,
        "unconfirmedSubsequentMessage": {
            "active": true,
            "message": "example",
            "delayInMinutes": 45
        },
        "unconfirmedFirstMessage": {
            "active": true,
            "message": "example",
            "delayInMinutes": 55
        },
        "confirmedAfterCheckOut": {
            "active": true,
            "message": "example",
            "delayInMinutes": 45
        },
        "confirmedDuringStay": {
            "active": true,
            "message": "example",
            "delayInMinutes": 45
        },
        "confirmedDayOfCheckOut": {
            "active": true,
            "message": "example",
            "delayInMinutes": 45
        },
        "confirmedDayOfCheckIn": {
            "active": true,
            "message": "example",
            "delayInMinutes": 45
        },
        "confirmedBeforeCheckIn": {
            "active": true,
            "message": "example",
            "delayInMinutes": 45
        }
    }
}
Attribute Type Description
answeringMachine Object
---active Boolean
---confirmedBeforeCheckIn Object
------active Boolean
------message String
------daysInMinutes Number
---confirmedDayOfCheckIn Object
------active Boolean
------message String
------daysInMinutes Number
---confirmedDayOfCheckOut Object
------active Boolean
------message String
------daysInMinutes Number
---confirmedDuringStay Object
------active Boolean
------message String
------daysInMinutes Number
---confirmedAfterCheckOut Object
------active Boolean
------message String
------daysInMinutes Number
---unconfirmedFirstMessage Object
------active Boolean
------message String
------daysInMinutes Number
---unconfirmedSubsequentMessage Object
------active Boolean
------message String
------daysInMinutes Number
hooks Object
---active Boolean
---ignoredHooks [String]-(ObjectId)
calendarSmartRules Object
---active Boolean
---blockListings [String]-(ObjectId)
homeAutomation Object
---buzzer Object
------active Boolean
------incomingNumber String
------toDial String
autoList Object
----active Boolean
----config [String]
autoReviews Object
---active Boolean
---daysBeforeSending Number
---templates [String]
---starRating Number
autoPricing Object
---active Boolean
---rules [Object]
------startingFromDaysAhead Number
------tillDaysAhead Number
------amount Number
------unit Enum %, currency
------subject Enum available, gaps, occupancy
------condition Object
---------amount Number
---------operator Enum $gte, $lte

The policy object

{
    "chargeType": "PERCENTAGE",
    "amount": 30,
    "useGuestCard": true,
    "_id": "59aebaf3edad8d0f00d68f55",
    "scheduleTo": {
        "reservationEvent": "CHECK_IN",
        "timeRelation": {
            "relation": "AT",
            "unit": "HOURS",
            "amount": 1
        }
    }
}
Attribute Type Description
chargeType Enum
amount Number
useGuestCard Boolean
scheduledTo Object
---reservationEvent Enum CHECK_IN, CHECK_OUT, CONFIRMATION
---timeRelation Object
------relation Enum AT, AFTER, BEFORE
------unit Enum SECONDS, MINUTES, HOURS, DAYS
------amount Number

The receptionistsService object

{
    "active": true,
    "contactPersonUserId": "5901fa614258fd10000b78e3",
    "reviews": {
        "monitorIncomingReviews": true,
        "writeReviewsForGuests": true,
        "monitorIncomingReviewsGuidelines": "these are the guidelines",
        "writeReviewsGuidelines": "these are the guidelines"
    },
    "screening": {
        "goOverChecklist": true,
        "ifSuccess": "approve",
        "ifFailed": "flag",
        "checklist": [
            {
                "item": "If you get",
                "_id": "59aeb934462d1a0f00d7b8a9"
            },
            {
                "item": "a ticket from this listing",
                "_id": "59aeb934462d1a0f00d7b8a8"
            },
            {
                "item": "just clear it",
                "_id": "59aeb934462d1a0f00d7b8a7"
            },
            {
                "item": "because it's a FAKE",
                "_id": "59aeb934462d1a0f00d7b8a6"
            }
        ]
    },
    "receptionDesk": {
        "textSupport": true,
        "smsSupport": true,
        "phoneSupport": true,
        "whiteLabel": true,
        "customImpersonation": "Impersonation",
        "customSignature": "Signature",
        "atPhones": [],
        "ittt": [
            {
                "ifThis": "This",
                "thenThat": "<p>That!</p>",
                "_id": "59aeccb6edad8d0f00d7c391"
            }
        ]
    }
}
Attribute Type Description
active Boolean
contactPersonUserId String (ObjectId)
receptionDesk Object
---ittt Object
------ifThis String
------thenThat String
---approveRequests Boolean
---textSupport Boolean
---smsSupport Boolean
---phoneSupport Boolean
---atPhones [String]
---reservationTask Boolean
---whiteLabel Boolean
---customImpersonation String
---customSignature String
screening Object
---goOverChecklist Boolean
---checklist Object
------item String
------isProactive Boolean
---ifFailed Enum flag, decline
---ifSuccess Enum flag, approve, ask
reviews Object
---monitorIncomingReviews Boolean
---monitorIncomingReviewsGuidelines String
---writeReviewsForGuests Boolean
---writeReviewsGuidelines String

The markups object

Attribute Type Description
manual valueScheme Object
airbnb valueScheme Object
agoda valueScheme Object
bookingCom valueScheme Object

Change Account object

    {
        "_id": "596f6fe706112710005d96ff",
        "...updatedFields"
    }

HTTP Request

PUT /accounts/me

Response

The requested account changes.

Attribute Structure Description
_id String Unique id
[Updated fields]

Delete Account object

HTTP Request

DELETE /accounts/me

Query Parameters

Parameter Default Description Example
shouldRevertEmail --- optional true
sendCancellationEmail --- optional false

Response

OK

Retrieve account stats

{
    "confirmed": {
        "value": 37
    },
    "checkins": {
        "value": 13
    },
    "avgPayout": {
        "value": 1540,
        "currency": "$"
    },
    "avgNights": {
        "value": 3.5
    },
    "avgGuests": {
        "value": 2.4
    },
    "avgDaysInAdvance": {
        "value": 31
    },
    "listingsCount": {
        "active": 4,
        "unlisted": 3
    }
}

HTTP Request

GET /accounts/:id/stats OR GET /accounts/me/stats

Query Parameters

Parameter Default Description Example
accountId --- Required with admin token, Unavailable with user token. 531968414930a7f09b075800
listingId --- Limit to a certain listing. If given no listingsCount is returned. 531967884930a7f09b0756e7

Response

Stats for the requested account/listing.

Attribute Structure Description
confirmed Object: value The amount of bookings that their createdAt is in the last 30 days
checkins Object: value The amount of bookings that their checkIn is in the last 30 days
avgPayout Object: value, currency The avg. hostPayout of bookings created in the last 30 days
avgNights Object: value The avg. nightsCount of bookings created in the last 30 days
avgGuests Object: value The avg. guestsCount of bookings created in the last 30 days
avgDaysInAdvance Object: value The avg. of days from booking.createdAt and booking.checkIn for bookings created in the last 30 days
listingsCount Object: active, unlisted Active is the number of managed and listed listings at the moment, Unlisted are managed and unlisted

Retrieve account's billing status

    {
        "status": "ok",
        "accountBalance": {
            "amount": 203,
            "currency": "$"
        },
        "nextBillingDate": "2015-09-24 14:30:22.744Z"
    }

HTTP Request

GET /accounts/:id/billing-status OR GET /accounts/me/billing-status

Response

Billing status for the requested user.

Attribute Structure Description
status Enum ok if all payments method haven't failed
missing if missing payment method
failed if there is a payment method that has failed.
accountBalance Object: amount, currency The credits available for the user
nextBillingDate Date The date for the next billing cycle

Create a stripe account for our account

    {
            "_id": "563e0b6a08a2710e00057b82",
            "timezone": "Asia/Jerusalem",
            "name": "BnbAir",
            "pms": {
                "paymentProcessing": {
                    "active": true,
                    "paymentProviders": {
                        "stripe": {
                            "accountName": "Poll dancers etc.",
                            "active": true,
                            "defaultCurrency": "usd",
                            "payload": {
                                "access_token": ACCESS_TOKEN,
                                "livemode": true,
                                "refresh_token": REFRESH_TOKEN,
                                "token_type": "bearer",
                                "stripe_publishable_key": PUBLISHABLE_KEY,
                                "stripe_user_id": USER_ID,
                                "scope": "read_write",
                                "id": "acct_19nmQxLYcJ0oiNhY"
                            },
                            "status": "ACTIVE",
                            "syncedAt": "2017-03-02T13:06:31.857Z"
                        }
                    }
                }
            },
            "billing": {
                "stripeCustomerId": CUSTOMER_ID,
                "prevBillingDate": "2017-07-03T15:30:50.174Z",
                "paymentMethods": [],
                "balance": {
                    "amount": 3,
                    "currency": "USD"
                },
                "nextBillingDate": "2017-07-10T15:30:50.174Z",
                "billingDay": 1,
                "billingCycle": "Weekly"
            },
            "id": "563e0b6a08a2710e00057b82"
        }

Body Parameters

Parameter Default
country US

HTTP Request

POST /accounts/:id/create-stripe-account OR POST /accounts/me/create-stripe-account

Response

Account object with updated paymentProcessingFeature field. Under 'paymentProcessingFeature.stripe.verification.fields_needed' you can find the missing fields for account verification

Update the stripe account

    {
            "_id": "563e0b6a08a2710e00057b82",
            "timezone": "Asia/Jerusalem",
            "name": "BnbAir",
            "pms": {
                "paymentProcessing": {
                    "active": true,
                    "paymentProviders": {
                        "stripe": {
                            "accountName": "Poll dancers etc.",
                            "active": true,
                            "defaultCurrency": "usd",
                            "payload": {
                                "access_token": ACCESS_TOKEN,
                                "livemode": true,
                                "refresh_token": REFRESH_TOKEN,
                                "token_type": "bearer",
                                "stripe_publishable_key": PUBLISHABLE_KEY,
                                "stripe_user_id": USER_ID,
                                "scope": "read_write",
                                "id": "acct_19nmQxLYcJ0oiNhY"
                            },
                            "status": "ACTIVE",
                            "syncedAt": "2017-03-02T13:06:31.857Z"
                        }
                    }
                }
            },
            "billing": {
                "stripeCustomerId": CUSTOMER_ID,
                "prevBillingDate": "2017-07-03T15:30:50.174Z",
                "paymentMethods": [],
                "balance": {
                    "amount": 3,
                    "currency": "USD"
                },
                "nextBillingDate": "2017-07-10T15:30:50.174Z",
                "billingDay": 1,
                "billingCycle": "Weekly"
            },
            "id": "563e0b6a08a2710e00057b82"
        }

Body Parameters

Same params as in stripe update account: Stripe api docs

HTTP Request

POST /accounts/:id/update-stripe-account OR POST /accounts/me/update-stripe-account

Response

Account object with updated paymentProcessingFeature field.

Connect a stripe account with Guesty account

    {
                "_id": "563e0b6a08a2710e00057b82",
                "timezone": "Asia/Jerusalem",
                "name": "BnbAir",
                "pms": {
                    "paymentProcessing": {
                        "active": true,
                        "paymentProviders": {
                            "stripe": {
                                "accountName": "Poll dancers etc.",
                                "active": true,
                                "defaultCurrency": "usd",
                                "payload": {
                                    "access_token": ACCESS_TOKEN,
                                    "livemode": true,
                                    "refresh_token": REFRESH_TOKEN,
                                    "token_type": "bearer",
                                    "stripe_publishable_key": PUBLISHABLE_KEY,
                                    "stripe_user_id": USER_ID,
                                    "scope": "read_write",
                                    "id": "acct_19nmQxLYcJ0oiNhY"
                                },
                                "status": "ACTIVE",
                                "syncedAt": "2017-03-02T13:06:31.857Z"
                            }
                        }
                    }
                },
                "billing": {
                    "stripeCustomerId": CUSTOMER_ID,
                    "prevBillingDate": "2017-07-03T15:30:50.174Z",
                    "paymentMethods": [],
                    "balance": {
                        "amount": 3,
                        "currency": "USD"
                    },
                    "nextBillingDate": "2017-07-10T15:30:50.174Z",
                    "billingDay": 1,
                    "billingCycle": "Weekly"
                },
                "id": "563e0b6a08a2710e00057b82"
            }

Body Parameters

Parameter Default Description Example
code null Stripe Authorization code

HTTP Request

POST /accounts/:id/connect-stripe-account OR POST /accounts/me/connect-stripe-account

Response

Account object with updated payments field. Under 'paymentProcessingFeature.stripe.id' you can find the ID of the connected stripe account Read more: Stripe api docs

[comment:] todo - check to see if this is the correct route. (should be post to /websites/ collection)

Check website name availability

    {
        "available": true
    }

HTTP Request

POST /accounts/website-name-availability

Response

Attribute Structure Description
available Boolean True if this website name is available to use, false otherwise

Get all custom fields

HTTP Request

GET /accounts/:Id/custom-fields/

Get custom field

HTTP Request

GET /accounts/:Id/custom-fields/{field_id}

Create new custom field

HTTP Request

POST /accounts/:Id/custom-fields/

Body

{ "customFields": [ { "isPublic": true, "key": "options_fields_name", "object": "reservation", "type": "enum", "options": [ "1", "2", "3" ] }, { "isPublic": true, "key": "text_fields_name", "object": "listing", "type": "text" }, { "isPublic": true, "key": "number_fields_name", "object": "listing", "type": "number" } ] }

Update custom field

IMPORTANT NOTE: The only field editable is 'Option' on 'enum' type Custom Fields. The whole object need to be sent

HTTP Request

PUT /accounts/:Id/custom-fields/

Body

{ "customFields": [ { "isPublic": true, "key": "options_fields_name", "object": "reservation", "type": "enum", "options": [ "1", "2", "3" ] } }

Delete custom field

HTTP Request

DELETE /accounts/me/custom-fields/{field_id}

Users

The user object

User Object

{
    "_id": "5901fa614258fd10000b78e3",
    "accountId": "563e0b6a08a2710e00057b82",
    "firstName": "Elad",
    "lastName": "Kremer",
    "fullName": "Elad Kremer",
    "email": "example@guesty.com",
    "preferredContactMethod": "email",
    "title": "RND",
    "displayLanguage": "en-US",
    "settings": {
        "notifications": {
            "subscriptions": [
                {
                    "type": "PAYMENT",
                    "name": "FAILED",
                    "_id": "5963924c2b5be11000077f67",
                    "targets": [
                        "DASHBOARD"
                    ]
                }
            ]
        }
    },
    "googleChromeNotificationsSubscriptionIds": [],
    "favs": {
       "views": [
         "d950dfa3c59aege3gffdd8f7",
         "556d95083cfdfe58e3fdd8f3",
         "556d9asffd59ae58e3fdd8f2"
       ]
     },
    "roles": [
        {
            "roleId": "57447a900ebc04ba98064035",
            "_id": "5961ed9396897b1000e9be47"
        }
    ],
    "phones": [
                 "15417543010",
                 "15417543012",
                 "15417543013"
             ],
    "emails": [
        "example@guesty.com",
        "example2@guesty.com"
    ],
    "tags": [
        "newguy",
        "new"
    ],
    "notes": "this is a note",
    "phone": "15417543010",
     "picture": {
            "thumbnail": "http://images.com/image_a.jpg",
            "regular": "http://images.com/image_b.jpg"
        },
    "__v": 5
}
Attribute Type Description
_id String Unique Id
accountId String Unique Id
firstName String
lastName String
fullName String 'firstName lastName'
email String Primary email address
preferredContactMethod Enum email, sms, call
title String
displayLanguage String (see below)
favs Object (see below) - missing
roles [Object] (see below)
phones [String] list of phone numbers
emails [String] list of emails
tags [String] list of tags
notes String
phone String Primary phone number
picture Object (see below)
settings Object
-----notifications Object
----------subscriptions [Object] (see below)
googleChromeNotificationsSubscriptionIds [String]

The displayLanguage object

Attribute Type Description
_displayLanguage Enum [en-US, es-ES, fr, de, it, nl, ja, cs,
_ [zh-CN, pt-PT, da, el, hr, hu, pl, ru, sk, ]

The settings : notifications : [subscriptions] object

{
       "settings": {
           "notifications": {
               "subscriptions": [
                   {
                       "type": "PAYMENT",
                       "name": "FAILED",
                       "_id": "5963924c2b5be11000077f67",
                       "targets": [
                           "DASHBOARD"
                       ]
                   }
               ]
           }
       },
}
Attribute Type Description
_id String Unique Id
type Enum TASK, PAYMENT, RESERVATION
name Enum FAILED, NEW_ATTACHMENT, CANCELED, ALTERATION, NEW_COMMENT
target [String] 'DASHBOARD', 'SMS'

The role object

{
    "roles": [
        {
            "roleId": "57447a900ebc04ba98064035",
            "_id": "58bd665b8f464b10002bf9f9"
        }
    ]
}
Attribute Type Description
roleId String unique role Id
listingIds [String] Array of listing Ids

The picture object

{
    "picture": {
        "thumbnail": "https://cdn.filepicker.io/api/file/bBnKEk8TlmJAUHcLApRx",
        "regular": "https://cdn.filepicker.io/api/file/bBnKEk8TlmJAUHcLApRx"
    }
}
Attribute Type Description
thumbnail String
regular String
large String

List all users

GET /users Response

{
    "results": [
      {
          "_id": "5901fa614258fd10000b78e3",
          "accountId": "563e0b6a08a2710e00057b82",
          "firstName": "Elad",
          "lastName": "Kremer",
          "fullName": "Elad Kremer",
          "email": "example@guesty.com",
          "preferredContactMethod": "email",
          "title": "RND",
          "displayLanguage": "en-US",
          "settings": {
              "notifications": {
                  "subscriptions": [
                      {
                          "type": "PAYMENT",
                          "name": "FAILED",
                          "_id": "5963924c2b5be11000077f67",
                          "targets": [
                              "DASHBOARD"
                          ]
                      }
                  ]
              }
          },
          "googleChromeNotificationsSubscriptionIds": [],
          "favs": {
             "views": [
               "d950dfa3c59aege3gffdd8f7",
               "556d95083cfdfe58e3fdd8f3",
               "556d9asffd59ae58e3fdd8f2"
             ]
           },
          "roles": [
              {
                  "roleId": "57447a900ebc04ba98064035",
                  "_id": "5961ed9396897b1000e9be47"
              }
          ],
          "phones": [
                       "15417543010",
                       "15417543012",
                       "15417543013"
                   ],
          "emails": [
              "example@guesty.com",
              "example2@guesty.com"
          ],
          "tags": [
              "newguy",
              "new"
          ],
          "notes": "this is a note",
          "phone": "15417543010",
           "picture": {
                  "thumbnail": "http://images.com/image_a.jpg",
                  "regular": "http://images.com/image_b.jpg"
              },
          "__v": 5
      }
    ],
    "count": 1,
    "fields": "",
    "limit": 25,
    "skip": 0
}

HTTP Request

GET /users

Query Parameters

Parameter Default Description Example
q null Search query string. Searches in fullName, emails, phones Koby Soto
fields null Selection of fields, separated by space firstName lastName email
limit 200 Pagination, max: 200 150
skip 0 Pagination 10

Response

Array of requested users

Retrieve a user

HTTP Request

User Object response

{
    "_id": "5901fa614258fd10000b78e3",
    "fullName": "Elad Kremer",
    "preferredContactMethod": "email",
    "firstName": "Elad",
    "lastName": "Kremer",
    "title": "RND",
    "email": "example@guesty.com",
    "accountId": "563e0b6a08a2710e00057b82",
    "displayLanguage": "en-US",
    "settings": {
        "notifications": {
            "subscriptions": [
                {
                    "type": "PAYMENT",
                    "name": "FAILED",
                    "_id": "5963924c2b5be11000077f67",
                    "targets": [
                        "DASHBOARD"
                    ]
                }
            ]
        }
    },
    "googleChromeNotificationsSubscriptionIds": [],
    "favs": {
       "views": [
         "d950dfa3c59aege3gffdd8f7",
         "556d95083cfdfe58e3fdd8f3",
         "556d9asffd59ae58e3fdd8f2"
       ]
     },
    "roles": [
        {
            "roleId": "57447a900ebc04ba98064035",
            "_id": "5961ed9396897b1000e9be47"
        }
    ],
    "phones": [
                 "15417543010",
                 "15417543012",
                 "15417543013"
             ],
    "emails": [
        "example@guesty.com",
        "example2@guesty.com"
    ],
    "tags": [
        "newguy",
        "new"
    ],
    "__v": 5,
    "notes": "this is a note",
    "phone": "15417543010",
     "picture": {
            "thumbnail": "http://images.com/image_a.jpg",
            "regular": "http://images.com/image_b.jpg"
        }
}

GET /users/:id OR GET /me

Query Parameters

Parameter Default Description Example
fields --- Selection of fields, separated by space firstName lastName email

Response

The requested user.

Update a user

HTTP Request

PUT /users/:id OR PUT /me

Response

Retrieve the updated user, selection of fields that were sent in body.

Create a user

Response

{
    "__v": 0,
    "fullName": "Uria Goldy",
    "email": "urigold@guesty.com",
    "accountId": "563e0b6a08a2710e00057b82",
    "_id": "59b9083432123a1000b50a9c",
    "settings": {
        "notifications": {
            "subscriptions": []
        }
    },
    "googleChromeNotificationsSubscriptionIds": [],
    "roles": [
        {
            "roleId": "57447a900ebc04ba98064035",
            "_id": "59b9083432123a1000b50a9d"
        }
    ],
    "phones": [],
    "emails": [
        "urigold@guesty.com"
    ],
    "tags": [],
    "id": "59b9083432123a1000b50a9c"
}

HTTP Request

POST /users

Body Parameters

Parameter Default Description
fullName Required Full guest name 'Ari Gold'
email Required (Unique) Valid email address
emails Required Array of of the users emails
password Required Strong password, atleast 6 characters long.

Example

Body

{ "fullName": "Uria Goldy", "email": "urigold@guesty.com", "password": "123456789", "emails": ["urigold@guesty.com"] }

Response

The created user.

Delete a user

HTTP Request

DELETE /users/:id

Validation

Cannot delete self, cannot delete last user in account.

Check email address availability

    {
        "available": true
    }

HTTP Request

POST /users/email-availability

Authorization

Accessible to everyone. No need to authenticate.

Body Parameters

Parameter Default Description
email Required The requested email

Response

Attribute Structure Description
available Boolean True if this email is available to use, false otherwise.

Open a support ticket

"OK"

HTTP Request

POST /users/:id/support OR POST /me/support

Body Parameters

Parameter Default Description Example
subject "Support issue" Subject line "Issue"
message --- Message to be included in the ticket "Issue"

Response

"OK"

Integrations

The integration object

{
    "_id": "5958c7e5884e961000817799",
    "accountId": "563e0b6a08a2710e00057b82",
    "rentalsUnited": {
        "ignored": {
            "listings": [],
            "reservations": []
        }
    },
    "flags": {
        "accountBlocked": {
            "sentTemplates": []
        },
        "accountDisabled": {
            "sentTemplates": []
        },
        "wrongPasswordDetected": {
            "sentTemplates": []
        },
        "twoStepVerification": {
            "sentTemplates": []
        },
        "accountIdVerification": {
            "sentTemplates": []
        }
    },
    "listingsList": [],
    "pendingTasks": [],
    "lastSynced": {
        "bookings": []
    },
    "incomingEmail": "naama@user.guesty.com",
    "__v": 0,
    "airbnb": {
        "importCalendars": true,
        "ignored": {
            "reservations": [],
            "listings": []
        },
        "emailsFromSupport": []
    },
    "forwardEmails": {
        "all": true,
        "emails": [
            "hipit10@hotmail.com"
        ]
    },
    "platform": "airbnb",
    "nickname": "naama"
}
Attribute Type Description
_id String Unique id
accountId String Owner
platform Enum [airbnb, rentalsUnited, manual]
id Number External ID
active Boolean Status of connection
nickname String
forwardEmails Object
---all Boolean
---confirmations Boolean
---inquiries Boolean
---requests Boolean
---reviews Boolean
---payments Boolean
---reminders Boolean
---emailsFromGuest Boolean
---externals Boolean
---emails [String]
---asGuest String
credentials Object
---username String
---password String
incomingEmail String
connectedAt Date
disconnectedAt Date
firstName String The name of the host as appears on that integration
lastName String The name of the host as appears on that integration
fullName String The name of the host as appears on that integration
birthDate String yyyy-mm-dd
externalLink String
listingsList Array @see POST /integrations/:id/retrieve-external-listings
airbnb Object Only if platform is airbnb
---emailsFromSupport [Object]
---ignored Object
------listings [String] external ids of deleted listings
------reservations [String] external ids of deleted reservations
rentalsUnited Object Only if platform is rentalsUnited
---ignored Object
------listings [String] external ids of deleted listings
------reservations [String] external ids of deleted reservations

airbnb object

Attribute Type Description
id Number The id of the user in Airbnb
incomingEmail String The email address that we receive emails from.
username String Login credentials for the Airbnb account.
password String Login credentials
forwardEmails Object Toggles to forward the incoming emails. Boolean value.
Fields include: all, confirmations, inquiries, payments, requests, reviews, reminders, emailsFromGuest, externals.
Field emails is an array of email addresses to be forwarded to.

rentalsUnited object

Attribute Type Description
id Number The id of the user in Airbnb
incomingEmail String The email address that we receive emails from
username String
password String

List all integrations

{
    "count": 1,
    "limit": 25,
    "skip": 0,
    "results": [
       { "_id": "58f77ff3f13d691000af7e12",
            "platform": "airbnb",
            "incomingEmail": "xxxxx@user.guesty.com",
            "accountId": "563e0b6a08a2710e00057b82",
            "active" : false,
            "nickname": "Test",
            "airbnb": {
                "importCalendars": false,
                "ignored": {
                    "reservations": [],
                    "listings": []
                },
                "emailsFromSupport": []
            },
            "listingsList": [],
            "pendingTasks": [],
            "lastSynced": {
                "bookings": []
            },
            "forwardEmails": {
                "emails": []
            },
            "__v": 0
        }
    ]
}

HTTP Request

GET /integrations

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space "platform incomingEmail credentials.username"
sort "nickname" ascending alphabetical sort , use - to descending sort nickname/-nickname
limit 25 Pagination, max: 100 25
skip 0 Pagination 0

Retrieve an integration

HTTP Request

GET /integrations/:id

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space. When null retrieve the main properties of the object. We recommend always specifying the specific fields you'd like to receive to ensure that you get them. Please see the full list above. "firstName lastName"

Response

Integration object.

Create an integration

Response

{
    "__v": 0,
    "platform": "airbnb",
    "incomingEmail": "sergrin2_ovzov6k@user.guesty.com",
    "accountId": "563e0b6a08a2710e00057b82",
    "nickname": "sergrin2_ovzov6k",
    "_id": "59b91f4a8e6bb3100021531f",
    "bookingCom": {
        "ignored": {
            "reservations": [],
            "listings": []
        }
    },
    "rentalsUnited": {
        "ignored": {
            "reservations": [],
            "listings": []
        }
    },
    "airbnb": {
        "importCalendars": true,
        "ignored": {
            "reservations": [],
            "listings": []
        },
        "emailsFromSupport": []
    },
    "flags": {
        "twoStepVerification": {
            "sentTemplates": []
        },
        "accountIdVerification": {
            "sentTemplates": []
        },
        "accountBlocked": {
            "sentTemplates": []
        },
        "accountDisabled": {
            "sentTemplates": []
        },
        "wrongPasswordDetected": {
            "sentTemplates": []
        }
    },
    "listingsList": [],
    "pendingTasks": [],
    "lastSynced": {
        "bookings": []
    },
    "forwardEmails": {
        "emails": []
    },
    "createAt": "2017-09-13T12:06:34.998Z",
    "permissions": []
}

HTTP Request

POST /integrations

Body

Parameter Default Description
platform Required rentalsUnited, airbnb, manual,

Example

Body

{"platform": "manual"}

Response

The created integration object.

Update an integration

HTTP Request

PUT /integrations/:id

Response

The updated integration with only the fields that were sent in body.

Retrieve all the external listings

    {
        "count": 1,
        "limit": 25,
        "skip": 0,
        "results": [

        ]
    }

HTTP Request

POST /integrations/:id/retrieve-external-listings

Response

OK

To get the results, query for integration with field listingsList. The format of listingsList:

Attribute Type
externalId String
title String
address String

Import external listings

Create listings from external listings

HTTP Request

POST /integrations/:id/import-external-listings

Body params

Parameter Default Description Example
externalIds Required String or array. The external ids of listings to import.

Response

OK

Listings

The Listing object

{
    "_id": "59ac245d27cb310f0017afe3",
    "accommodates": 2,
    "bedrooms": 1,
    "beds": 1,
    "bathrooms": 1,
    "defaultCheckInTime": "15:00",
    "defaultCheckOutTime": "10:00",
    "propertyType": "Apartment",
    "roomType": "Entire home/apt",
    "timezone": "Asia/Jerusalem",
    "nickname": "ETDT",
    "title": "example listing",
    "accountId": "563e0b6a08a2710e00057b82",
    "occupancyStats": [],
    "preBooking": [],
    "importedAt": "2017-09-03T15:48:45.072Z",
    "offeredServices": [],
    "calendarRules": {
        "rentalPeriods": [],
        "seasonalMinNights": []
    },
    "customFields": [],
    "active": true,
    "receptionistsService": {},
    "sales": {
        "salesService": {
            "atPhones": []
        }
    },
    "pms": {
        "active": true,
        "cleaningStatus": {
            "markAsDirtyOnCheckIn": null,
            "statusFade": null,
            "active": true
        },
        "autoPayments": {
            "policy": []
        },
        "tasks": {
            "defaultTasks": []
        },
        "automation": {
            "autoList": {},
            "autoPricing": {},
            "autoReviews": {},
            "homeAutomation": {},
            "calendarSmartRules": {},
            "hooks": {},
            "answeringMachine": {}
        }
    },
    "prices": {
        "currency": "EUR",
        "basePrice": 859,
        "guestsIncludedInRegularFee": 5,
        "weeklyPriceFactor": 0.95,
        "monthlyPriceFactor": 0.9,
        "cleaningFee": 35,
        "securityDepositFee": 350,
        "extraPersonFee": 10
    },
    "terms": {
        "minNights": 1,
        "maxNights": 45
    },
    "amenitiesNotIncluded": [
        "TV",
        "Cable TV",
        "Internet",
        "Wireless Internet",
        "Air conditioning",
        "Pool",
        "Kitchen"
    ],
    "amenities": [
        "Microwave",
        "Smoke detector",
        "Laptop friendly workspace",
        "Bathtub",
        "Refrigerator",
        "Stove"
    ],
    "pictures": [],
    "picture": {
        "thumbnail": "https://cdn.filepicker.io/api/file/BE7EpDKNSviVKIRUw91o"
    },
    "address": {
        "full": "Kaplan St 2, Ramat Gan, Israel",
        "lng": 34.8202173,
        "lat": 32.0695525,
        "street": "Kaplan Street 2",
        "city": "Ramat Gan",
        "country": "Israel"
    },
    "tags": [],
    "pendingTasks": [],
    "integrations": [],
    "createdAt": "2017-09-03T15:48:45.070Z",
    "__v": 1,
    "isListed": true,
    "cleaningStatus": {
        "value": "unknown"
    }
}
Attribute Type Description
_id String (ObjectId) Unique id
accountId String (ObjectId) Unique id
createdAt Date
integrations Object (see below)
isVirtual Boolean
nickname String
tags [String]
isListed Boolean
title String
propertyType String
roomType String
bedType String
accommodates Number
bedrooms Number
areaSquareFeet Number
address Object (see below)
publishedAddress Object (see below)
timezone String
defaultCheckInTime String
defaultCheckOutTime String
cleaning Object (see below)
cleaningStatus Object (see below)
picture Object (see below)
pictures [pictures] (see below)
amenities [String]
amenitiesNotIncluded [String]
terms Object (see below)
prices Object (see below) & Please see Financial section
netIncomeFormula String
commissionFormula String
commissionTaxPrecentage String
pms Object (see below)
receptionistsService Object (see below)
active Boolean
customFields Object (see below)
calendarRules Object (see below)
publicDescription Object (see below)
privateDescription Object (see below)
markups Object (see below)

The integrations object

[
    {
        "platform" : "airbnb",
        "_id" : "571cb924a843c10e000dflk23",
        "externalUrl" : "https://www.airbnb.com/rooms/20392984",
        "airbnb" : {
            "starRating" : 4.5,
            "reviewsCount" : 57,
            "id" : 20392984,
            "importCalendar" : false,
            "isCalendarSynced" : true
        }
    },
    {
        "platform" : "rentalsUnited",
        "_id" : "56cd9ab369a2100e00dflk23",
        "rentalsUnited" : {
            "id" : 264100,
            "currency" : "EUR",
            "locationId" : "4558"
        }
    }
]
Attribute Type Description
_id String
platform Enum airbnb, rentalsUnited, manual, bookingCom or homeaway
airbnb Object Details related to Airbnb
---id Number
---reviewsCount Number
---starRating Number
---importCalendar Boolean
---isCalendarSynced Boolean
rentalsUnited Object Details related to RU
---id Number
---currency String
---locationId String
bookingCom Object Details related to bookingCom
---id Number
---hotelId Number
---rateId Number
---currency String
markup Object
---amount Number
---units String

The address object

{
    "full": "Kaplan St 2, Ramat Gan, Israel",
    "lng": 34.8202173,
    "lat": 32.0695525,
    "street": "Kaplan Street 2",
    "city": "Ramat Gan",
    "country": "Israel"
}
Attribute Type Description
full String
city String
state String
country String
zipcode String
neighborhood String
street String
apt String
lat Number
lng Number
searchable String
floor Number

The publishedAddress object

{
    "full": "73 High St, Irvine KA12 0AL, UK",
    "lng": -4.6662351,
    "lat": 55.6144919,
    "street": "High Street 73",
    "city": "Irvine",
    "country": "United Kingdom"
}
Attribute Type Description
full String
city String
state String
country String
zipcode String
neighborhood String
street String
apt String
lat Number
lng Number
searchable String
floor Number

The cleaning object

Attribute Type Description
defaultCleaningTime String
instructions String

The cleaningStatus object

Attribute Type Description
value Enum clean, dirty, unknown
updatedAt Date

The picture object

Attribute Type Description
thumbnail String
regular String
large String
caption String

The pictures object

[
    {
        "original": "https://cdn.filepicker.io/api/file/BE7EpDKNSviVKIRUw91o",
        "thumbnail": "https://cdn.filepicker.io/api/file/BE7EpDKNSviVKIRUw91o",
        "_id": "59ac245d27cb310f0017afe5"
    },
    {
        "original": "https://cdn.filepicker.io/api/file/zpZ1l5QaSAatCLXasslZ",
        "thumbnail": "https://cdn.filepicker.io/api/file/zpZ1l5QaSAatCLXasslZ",
        "_id": "59ac245d27cb310f0017afe4"
    }
]
Attribute Type Description
_id String (ObjectId)
thumbnail String
regular String
large String
caption String
original String
isProfessional Boolean
sort Number ascending numeric sort , use - to descending sort

The terms object

{
    "minNights": 1,
    "maxNights": 45
}
Attribute Type Description
minNights Number
maxNights Number
cancellation String

The prices object

{
    "currency": "EUR",
    "basePrice": 859,
    "guestsIncludedInRegularFee": 5,
    "weeklyPriceFactor": 0.95,
    "monthlyPriceFactor": 0.9,
    "cleaningFee": 35,
    "securityDepositFee": 350,
    "extraPersonFee": 10
}

Please see Financial section

Attribute Type Description
guestsIncludedInRegularFee Number
extraPersonFee Number
basePrice Number
basePriceUSD Number
monthlyPriceFactor Number
weeklyPriceFactor Number
weeendBasePrice Number
securityDepositFee Number
currency String
cleaningFee Number

The receptionistsService object

{
    "active": true,
    "contactPersonUserId": "5901fa614258fd10000b78e3",
    "reviews": {
        "monitorIncomingReviews": true,
        "writeReviewsForGuests": true,
        "monitorIncomingReviewsGuidelines": "these are the guidelines",
        "writeReviewsGuidelines": "these are the guidelines"
    },
    "screening": {
        "goOverChecklist": true,
        "ifSuccess": "approve",
        "ifFailed": "flag",
        "checklist": [
            {
                "item": "If you get",
                "_id": "59aeb934462d1a0f00d7b8a9"
            },
            {
                "item": "a ticket from this listing",
                "_id": "59aeb934462d1a0f00d7b8a8"
            },
            {
                "item": "just clear it",
                "_id": "59aeb934462d1a0f00d7b8a7"
            },
            {
                "item": "because it's a FAKE",
                "_id": "59aeb934462d1a0f00d7b8a6"
            }
        ]
    },
    "receptionDesk": {
        "textSupport": true,
        "smsSupport": true,
        "phoneSupport": true,
        "whiteLabel": true,
        "customImpersonation": "Impersonation",
        "customSignature": "Signature",
        "atPhones": [],
        "ittt": [
            {
                "ifThis": "This",
                "thenThat": "<p>That!</p>",
                "_id": "59aeccb6edad8d0f00d7c391"
            }
        ]
    }
}
Attribute Type Description
active Boolean
contactPersonUserId String (ObjectId)
receptionDesk Object
---ittt Object
------ifThis String
------thenThat String
---approveRequests Boolean
---textSupport Boolean
---smsSupport Boolean
---phoneSupport Boolean
---atPhones [String]
---reservationTask Boolean
---whiteLabel Boolean
---customImpersonation String
---customSignature String
screening Object
---goOverChecklist Boolean
---checklist Object
------item String
------isProactive Boolean
---ifFailed Enum flag, decline
---ifSuccess Enum flag, approve, ask
reviews Object
---monitorIncomingReviews Boolean
---monitorIncomingReviewsGuidelines String
---writeReviewsForGuests Boolean
---writeReviewsGuidelines String

The customFields object

[
    {
        "fieldId": "58aecc18c982ba1a00aac98e",
        "value": "INSTRUCTIONS!",
        "_id": "59aecd66462d1a0f00d99823"
    }
]
Attribute Type Description
fieldId String (ObjectId)
value Mixed
fullText String

The calendarRules object

{
        "defaultAvailability" : "AVAILABLE",
        "advanceNotice" : {
            "defaultSettings" : {
                "hours" : 0,
                "allowRequestToBook" : false
            }
        },
        "bookingWindow" : {
            "defaultSettings" : {
                "days" : 180
            }
        },
        "weekendMinNights" : 2,
        "rentalPeriods" : [ ],
        "seasonalMinNights" : [
            {
                "_id" : ObjectId("5de3609d3eccc9003158ed74"),
                "from" : "2020-12-01",
                "to" : "2021-12-01",
                "minNights" : 1
            },
            {
                "_id" : ObjectId("5de3609d3eccc9003158ed75"),
                "from" : "2020-02-29",
                "to" : "2020-11-30",
                "minNights" : 4
            }
        ]
}
Attribute Type Description
defaultAvailability Enum AVAILABLE/BLOCKED
seasonalMinNights [seasonMinNights]
---from String
---to String
rentalPeriods [rentalPeriods]
---from String
---to String
advanceNotice [advanceNotice]
---defaultSettings Object
------hours Number
------allowRequestToBook Boolean
bookingWindow [bookingWindow]
---defaultSettings Object
------days Number

The advanceNotice object

Attribute Type Description
defaultSettings Object
---hours Number
---allowRequestToBook Boolean

The rentalPeriods object

Attribute Type Description
_id ObjectId
from String
to String

The bookingWindow object

Attribute Type Description
defaultSettings Object
---days Number

The privateDescription object

Attribute Type Description
directions String
houseManual String
wifi Object
---network String
---password String

The markups object

Attribute Type Description
manual valueScheme Object (see below)
airbnb valueScheme Object (see below)
agoda valueScheme Object (see below)
bookingCom valueScheme Object (see below)

The valueSchema object

Attribute Type Description
amount Number
units enum PERCENTAGE

The publicDescription object

{
    "summary": "this is the summary",
    "space": "this is the space3",
    "access": "guest access FTW",
    "neighborhood": "the neighborhood is humping",
    "transit": "easy peazy",
    "notes": "just noting some more stuff",
    "interactionWithGuests": "this is my interaction"
}
Attribute Type Description
summery String
space String
access String
neighborhood String
transit String
notes String
houseRules String
interactionWithGuests String

The sales object

Attribute Type Description
distribution Boolean
salesService Object
textual Boolean
phone Boolean
atPhones [String]

The pms object

{
    "active": true,
    "cleaningStatus": {
        "markAsDirtyOnCheckIn": true,
        "statusFade": {
            "active": true,
            "days": 15,
            "toStatus": "dirty"
        }
    },
    "autoPayments": {
        "policy": []
    },
    "tasks": {
        "defaultTasks": []
    },
    "automation": {}
}
Attribute Type Description
active Boolean
automation Object (see below)
inbox Object
---customSignature String
cleaningStatus Object
---active Boolean
---markAsDirtyOnCheckIn Boolean
---statusFade Object
------active Boolean
------days Number
------toStatus Enum unknown, dirty
paymentProcessing Object
---active Boolean
autoPayments Object
---policy [policy] (see below)

The automation object

{
    "autoList": {
        "config": [
            "101110111101011101101111",
            "110110111101111101111011",
            "110110101011011101101111",
            "110110111001011101101111",
            "101110111101010101111111",
            "111100111101011101101111",
            "111110111101011101101111"
        ],
        "active": true
    },
    "autoPricing": {
        "active": true,
        "rules": [
            {
                "startingFromDaysAhead": 4,
                "tillDaysAhead": 10,
                "amount": -10,
                "unit": "%",
                "subject": "available",
                "_id": "59aea8faf2fc8c9a00ac02f2",
                "condition": {
                    "amount": 3
                }
            }
        ]
    },
    "autoReviews": {
        "starRating": 5,
        "daysBeforeSending": 3,
        "active": true,
        "templates": [
            "example number one",
            "example number two"
        ]
    },
    "homeAutomation": {
        "buzzer": {
            "toDial": "2",
            "active": true,
            "incomingNumber": "97250404534"
        }
    },
    "calendarSmartRules": {
        "active": true,
        "blockListings": [
            "59a415396f6f010f0099b391"
        ]
    },
    "hooks": {
        "active": true,
        "ignoredHooks": []
    },
    "answeringMachine": {
        "active": true,
        "unconfirmedSubsequentMessage": {
            "active": true,
            "message": "example",
            "delayInMinutes": 45
        },
        "unconfirmedFirstMessage": {
            "active": true,
            "message": "example",
            "delayInMinutes": 55
        },
        "confirmedAfterCheckOut": {
            "active": true,
            "message": "example",
            "delayInMinutes": 45
        },
        "confirmedDuringStay": {
            "active": true,
            "message": "example",
            "delayInMinutes": 45
        },
        "confirmedDayOfCheckOut": {
            "active": true,
            "message": "example",
            "delayInMinutes": 45
        },
        "confirmedDayOfCheckIn": {
            "active": true,
            "message": "example",
            "delayInMinutes": 45
        },
        "confirmedBeforeCheckIn": {
            "active": true,
            "message": "example",
            "delayInMinutes": 45
        }
    }
}
Attribute Type Description
answeringMachine Object
---active Boolean
---confirmedBeforeCheckIn Object
------active Boolean
------message String
------daysInMinutes Number
---confirmedDayOfCheckIn Object
------active Boolean
------message String
------daysInMinutes Number
---confirmedDayOfCheckOut Object
------active Boolean
------message String
------daysInMinutes Number
---confirmedDuringStay Object
------active Boolean
------message String
------daysInMinutes Number
---confirmedAfterCheckOut Object
------active Boolean
------message String
------daysInMinutes Number
---unconfirmedFirstMessage Object
------active Boolean
------message String
------daysInMinutes Number
---unconfirmedSubsequentMessage Object
------active Boolean
------message String
------daysInMinutes Number
hooks Object
---active Boolean
---ignoredHooks [String]-(ObjectId)
calendarSmartRules Object
---active Boolean
---blockListings [String]-(ObjectId)
homeAutomation Object
---buzzer Object
------active Boolean
------incomingNumber String
------toDial String
autoList Object
----active Boolean
----config [String]
autoReviews Object
---active Boolean
---daysBeforeSending Number
---templates [String]
---starRating Number
autoPricing Object
---active Boolean
---rules [Object]
------startingFromDaysAhead Number
------tillDaysAhead Number
------amount Number
------unit Enum %, currency
------subject Enum available, gaps, occupancy
------condition Object
---------amount Number
---------operator Enum $gte, $lte

The policy object

{
    "chargeType": "PERCENTAGE",
    "amount": 30,
    "useGuestCard": true,
    "_id": "59aebaf3edad8d0f00d68f55",
    "scheduleTo": {
        "reservationEvent": "CHECK_IN",
        "timeRelation": {
            "relation": "AT",
            "unit": "HOURS",
            "amount": 1
        }
    }
}
Attribute Type Description
chargeType Enum
amount Number
useGuestCard Boolean
scheduledTo Object
---reservationEvent Enum CHECK_IN, CHECK_OUT, CONFIRMATION
---timeRelation Object
------relation Enum AT, AFTER, BEFORE
------unit Enum SECONDS, MINUTES, HOURS, DAYS
------amount Number

List all listings

{
    "results": [
        {
            "_id": "59ac245d27cb310f0017afe3",
            "accommodates": 2,
            "bedrooms": 1,
            "beds": 1,
            "bathrooms": 1,
            "defaultCheckInTime": "15:00",
            "defaultCheckOutTime": "10:00",
            "propertyType": "Apartment",
            "roomType": "Entire home/apt",
            "timezone": "Asia/Jerusalem",
            "nickname": "ETDT",
            "title": "Example listing",
            "accountId": "563e0b6a08a2710e00057b82",
            "occupancyStats": [],
            "preBooking": [],
            "importedAt": "2017-09-03T15:48:45.072Z",
            "offeredServices": [],
            "calendarRules": {
                "rentalPeriods": [],
                "seasonalMinNights": []
            },
            "customFields": [],
            "active": true,
            "receptionistsService": {},
            "sales": {
                "salesService": {
                    "atPhones": []
                }
            },
            "pms": {
                "active": true,
                "cleaningStatus": {},
                "autoPayments": {
                    "policy": []
                },
                "tasks": {
                    "defaultTasks": []
                },
                "automation": {
                    "autoList": {},
                    "autoPricing": {},
                    "autoReviews": {},
                    "homeAutomation": {},
                    "calendarSmartRules": {},
                    "hooks": {},
                    "answeringMachine": {}
                }
            },
            "prices": {
                "currency": "EUR",
                "basePrice": 859,
                "guestsIncludedInRegularFee": 5,
                "weeklyPriceFactor": 0.95,
                "monthlyPriceFactor": 0.9,
                "cleaningFee": 35,
                "securityDepositFee": 350,
                "extraPersonFee": 10
            },
            "terms": {
                "minNights": 1,
                "maxNights": 45
            },
            "amenitiesNotIncluded": [],
            "amenities": [],
            "pictures": [],
            "picture": {
                "thumbnail": "https://cdn.filepicker.io/api/file/BE7EpDKNSviVKIRUw91o"
            },
            "address": {},
            "tags": [
                "tag56",
                "tag2"
            ],
            "pendingTasks": [],
            "integrations": [],
            "SaaS": {
                "autoRenew": true
            },
            "createdAt": "2017-09-03T15:48:45.070Z",
            "__v": 6,
            "isListed": false,
            "cleaningStatus": {
                "value": "unknown"
            },
            "publishedAddress": {},
            "cleaning": {},
            "publicDescription": {}
        }
    ],
    "title": "Listings Report",
    "count": 1,
    "fields": "",
    "limit": 25,
    "skip": 0
}

HTTP Request

GET /listings

Query Parameters

Parameter Default Description Example
ids null Limit results to these ids
nids null Limit results to not include these ids
viewId null Pull a specific view (view is a saved settings of accountId, filters, fields,sort) 556d95083c59ae58e3fdd8f4
q null Search query string. Searches in title, internalNote, address.full "Cozy luxurious"
city null Limit results to city
active true Limit results to active state. Boolean, true for only active, false for only inactive, don't include for all.
pmsActive null Limit results to listings with the feature "pms" active. Boolean, true for only active, false for only inactive, don't include for all.
integrationId null Limit results to specific integration "531968414930a7f09b075800"
listed null Limit results to listed state. Boolean, true for only listed, false for only unlisted, don't include for all.
available null Limit results to only available listings in specific dates {"checkIn": "yyyy-mm-dd", "checkOut": "yyyy-mm-dd", "minOccupancy": 3}
tags null Limit results to listings with specific tag, can be used multiple times for and function tags=kinesu&tags=ExtendedStay
fields null Selection of fields, separated by space "title address"
sort "title" ascending alphabetical sort , use - to descending sort title/-title
limit 25 Pagination, max: 100 25
skip 0 Pagination 0

Response

Array of requested listings

Retrieve listing Financials

{
    "guestsIncludedInRegularFee": 4,
    "currency": "EUR",
    "basePriceUSD": 28,
    "basePrice": 100,
    "securityDepositFee": null,
    "extraPersonFee": 200,
    "weeklyPriceFactor": 0.89,
    "monthlyPriceFactor": 0.89,
    "cleaningFee": {
        "lastUpdated": "2018-04-25T13:10:53.665Z",
        "value": {
            "valueType": "PERCENTAGE",
            "multiplier": "PER_STAY",
            "formula": 0
        },
        "airbnb": {
            "value": {
                "formula": 0,
                "multiplier": "PER_STAY",
                "valueType": "FIXED",
                "_id": "5ae07e5d0e9598001f2fa9a8"
            }
        },
        "rentalsUnited": {
            "status": "MANUALLY_ALTERED",
            "value": {
                "valueType": "FIXED",
                "multiplier": "PER_STAY",
                "formula": 54,
                "_id": "5ae07e5d0e9598001f2fa9a9"
            },
            "homeAway": {
                "value": {
                    "formula": 5,
                    "valueType": "PERCENTAGE",
                    "multiplier": "PER_STAY",
                    "_id": "5ae07cef6299df001faa860f"
                }
            },
            "expedia": {
                "value": {
                    "formula": 0,
                    "valueType": "PERCENTAGE",
                    "multiplier": "PER_STAY",
                    "_id": "5ae071069ab7e3001f65bc9b"
                }
            },
            "despegar": {
                "value": {
                    "formula": 5,
                    "valueType": "PERCENTAGE",
                    "multiplier": "PER_STAY",
                    "_id": "5ae07cef6299df001faa8610"
                }
            },
            "bookingCom": {
                "value": {
                    "formula": 5,
                    "valueType": "PERCENTAGE",
                    "multiplier": "PER_STAY",
                    "_id": "5ae07cef6299df001faa860e"
                }
            }
        }
    }
}

Description

The new financials object represents the new setup of listing financials and specifically the Cleaning Fee in Guesty. This is a sub object of Listing and replaces the prices object under listing.

HTTP Request

GET /financials/listing/:listingId

The financials object

Attribute Type Description
guestsIncludedInRegularFee Number Same as in prices
extraPersonFee Number Same as in prices
basePrice Number Same as in prices
basePriceUSD Number Same as in prices
monthlyPriceFactor Number Same as in prices
weeklyPriceFactor Number Same as in prices
weeendBasePrice Number Same as in prices
securityDepositFee Number Same as in prices
currency String Same as in prices
cleaningFee Object Supports the new cleaning fee feature in Guesty.
---value Object Default settings for cleaning fee
------valueType Enum FIXED, PERCENTAGE
------multiplier Enum PER_STAY, PER_GUEST, PER_NIGHT, PER_GUEST_PER_NIGHT,
------formula Number Fixed price or %.
---lastUpdatedAt Date Last update date.

Per channel settings will be saved as the channel name - airbnb, rentalsUnited, bookingCom.

Authorization

Only accessible to Admin or User tokens.

Response

The requested listings' financial object.

Update listing Financials

HTTP Request

PUT /financials/listing/:listingId

Authorization

Only accessible to Admin or User tokens.

Body

{<Field>:<Updated value>}

Response

The updated financial object.

Create a listing

Response:

{
    "__v": 0,
    "title": "example listing",
    "accountId": "563e0b6a08a2710e00057b82",
    "timezone": "Asia/Jerusalem",
    "_id": "59b8f53a0454a61000a34a31",
    "occupancyStats": [],
    "preBooking": [],
    "importedAt": "2017-09-13T09:07:06.450Z",
    "offeredServices": [],
    "calendarRules": {
        "rentalPeriods": [],
        "seasonalMinNights": []
    },
    "customFields": [],
    "active": true,
    "receptionistsService": {
        "screening": {
            "checklist": []
        },
        "receptionDesk": {
            "atPhones": [],
            "ittt": []
        }
    },
    "sales": {
        "salesService": {
            "atPhones": []
        }
    },
    "pms": {
        "active": true,
        "autoPayments": {
            "policy": []
        },
        "tasks": {
            "defaultTasks": []
        },
        "automation": {
            "autoPricing": {
                "rules": []
            },
            "autoReviews": {
                "templates": []
            },
            "calendarSmartRules": {
                "blockListings": []
            },
            "hooks": {
                "ignoredHooks": []
            },
            "answeringMachine": {
                "unconfirmedSubsequentMessage": {
                    "delayInMinutes": 45
                },
                "unconfirmedFirstMessage": {
                    "delayInMinutes": 55
                },
                "confirmedAfterCheckOut": {
                    "delayInMinutes": 45
                },
                "confirmedDuringStay": {
                    "delayInMinutes": 45
                },
                "confirmedDayOfCheckOut": {
                    "delayInMinutes": 45
                },
                "confirmedDayOfCheckIn": {
                    "delayInMinutes": 45
                },
                "confirmedBeforeCheckIn": {
                    "delayInMinutes": 45
                }
            }
        }
    },
    "amenitiesNotIncluded": [],
    "amenities": [],
    "pictures": [],
    "address": {
        "full": "Eliezer Kaplan St 2, Tel Aviv-Yafo, Israel",
        "street": "Eliezer Kaplan Street 2",
        "city": "Tel Aviv-Yafo",
        "country": "Israel",
        "lat": 32.0733456,
        "lng": 34.78202479999999
    },
    "tags": [],
    "pendingTasks": [],
    "integrations": [],
    "SaaS": {
        "autoRenew": true
    },
    "plan": [
        {
            "name": "SOFTWARE",
            "planType": "RESERVATION_COMMISSION",
            "isLocked": true,
            "id": null
        },
        {
            "name": "RECEPTIONISTS_SERVICE",
            "planType": "RESERVATION_COMMISSION",
            "isLocked": true,
            "id": null
        },
        {
            "name": "RENTALS_UNITED",
            "planType": "RESERVATION_COMMISSION",
            "isLocked": true,
            "id": null
        },
        {
            "name": "AIRBNB",
            "planType": "RESERVATION_COMMISSION",
            "isLocked": true,
            "id": null
        }
    ],
    "createdAt": "2017-09-13T09:07:06.448Z",
    "id": "59b8f53a0454a61000a34a31"
}

HTTP Request

POST /listings

Authorization

Only accessible to Admin or User tokens.

Body

Parameter Default Description
address Requiered Any full address will do, we advise using the full property (the data will be parsed to the rest of the fields)

PMS is automatically ON for this listing.

Example

Body

{"address":{"full": "Eliezer Kaplan St 2, Tel Aviv-Yafo, Israel"}, "title": "example listing"}

Retrieve a listing

{
            "_id": "59ac245d27cb310f0017afe3",
            "accommodates": 2,
            "bedrooms": 1,
            "beds": 1,
            "bathrooms": 1,
            "defaultCheckInTime": "15:00",
            "defaultCheckOutTime": "10:00",
            "propertyType": "Apartment",
            "roomType": "Entire home/apt",
            "timezone": "Asia/Jerusalem",
            "nickname": "ETDT",
            "title": "Example listing",
            "accountId": "563e0b6a08a2710e00057b82",
            "occupancyStats": [],
            "preBooking": [],
            "importedAt": "2017-09-03T15:48:45.072Z",
            "offeredServices": [],
            "calendarRules": {},
            "customFields": [],
            "active": true,
            "receptionistsService": {},
            "sales": {},
            "pms": {
                "active": true,
                "cleaningStatus": {},
                "autoPayments": {},
                "tasks": {},
                "automation": {}
            },
            "prices": {},
            "terms": {
                "minNights": 1,
                "maxNights": 45
            },
            "amenitiesNotIncluded": [],
            "amenities": [],
            "pictures": [],
            "picture": {},
            "address": {},
            "tags": [
                "tag56",
                "tag2"
            ],
            "pendingTasks": [],
            "integrations": [],
            "SaaS": {},
            "createdAt": "2017-09-03T15:48:45.070Z",
            "__v": 9,
            "isListed": false,
            "cleaningStatus": {},
            "publishedAddress": {},
            "cleaning": {},
            "publicDescription": {}
        }

HTTP Request

GET /listings/:id

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space "title address"

Response

Listing object

Update a listing

HTTP Request

PUT /listings/:id

Response

Retrieve the updated listing, selection of fields that were sent in body.

Availability settings

HTTP Request

PUT /listings/:id/availability-settings

Body

Parameter Default Description Example
calendarRules Requiered Main Object -------
defaultAvailability ------- The default availability of the listing AVAILABLE/BLOCKED
advanceNotice ------- ------- Please see advanceNotice object
rentalPeriods ------- ------- Please see rentalPeriods object
bookingWindow ------- ------- Please see bookingWindow object

Response

The updated object.

Add new integration for a listing

{
    "_id": "59b928bb8e6bb31000219e58",
    "integrations": [
        {
            "platform": "rentalsUnited",
            "_id": "596b6f5aa6bd32100050be2a"
        },
        {
            "platform": "airbnb",
            "_id": "563e0b6a08a2710e00057b83"
        }
    ],
    "id": "59b928bb8e6bb31000219e58"
}

HTTP Request

POST /listings/:id/integrations

Body

Parameter Default Description
_id Required id of the integration to add

Example

Body

{"_id":"563e0b6a08a2710e00057b83"}

Response

Retrieve the updated listing, with the selection of only integrations field.

List all cities

[
    "Burnt Ranch",
    "New York",
    "Autun",
    "Kfar Sirkin",
    "London",
    "Newton",
    "Atlanta",
    "Montpelier",
    "Tel Aviv-Yafo",
    "Decatur",
    "Vancouver",
    "Amsterdam",
    "Cuyahoga Falls",
    "Palo Alto",
    "Ramat Gan"
]

HTTP Request

GET /listings/cities

Response

Array of cities (strings).

List all tags

[
    "Tag A",
    "Tag B",
    "Tag C"
]

HTTP Request

GET /listings/tags

Response

Array of tags (strings).

Export as CSV

HTTP Request

POST /listings.csv

Same as GET /listings but results are returned as a downloadable csv file

Send results in email

HTTP Request

POST /listings.email

Same as /listings but results are sent as an email

Body Parameters

Parameter Default Description Example
to Required Address of recipient koby@guesty.com

Get all custom fields- Listings

HTTP Request

GET /listings/:Id/custom-fields/

Get custom field-Listings

HTTP Request

GET /listings/:Id/custom-fields/{field_id}

Update Listing's Custom Fields

HTTP Request

PUT /listings/:Id/custom-fields

Body

{ "customFields": [ { "fieldId": "{{fieldId}}", "value": "{{value}}" } ] }

Parameter Default Description Example
fieldId ------- the field id "5f744b491af840002ca636a2"
value ------- The text field name Door code

Response

The updated object.

Delete Listing's Custom Fields

HTTP Request

DELETE /listings/{listing_id}/custom-fields/{field_id}

Listing's calendar

The Calendar day object

 {
        "_id": "5e2f1a9d6d808d0022e63c60",
        "date": "2020-05-05",
        "listingId": "5e2f1a94b189e6008fcd8293",
        "status": "unavailable",
        "priceUsd": 1654,
        "accountId": "563e0b6a08a2710e00057b82",
        "lastSyncedAt": "2020-01-28T06:55:09.301Z",
        "note": "",
        "currency": "CAD",
        "blocks": {
            "m": false,
            "r": false,
            "b": false,
            "bd": true,
            "sr": false,
            "abl": false,
            "a": false,
            "bw": false,
            "o": false,
            "an": true
        },
        "minNights": 7,
        "price": 10000,
        "notDefaultAvailability": true,
        "isBasePrice": true,
        "listing": {
            "_id": "5e2f1a94b189e6008fcd8293",
            "prices": {
                "currency": "CAD"
            }
Attribute Type Description
date String (Date) Format: YYYY-MM-DD
accountId String (ObjectId) ref to Account
listingId String (ObjectId) ref to Listing
status String (Enum) available, unavailable, reserved, booked
note String
price Number The price that that day cost
minNights Number The minimum reservation nights if reservation check in is on this day
currency String (Enum) 3 letter iso currency code
reservationId String (ObjectId) Linked reservation (Only if booked or reserved)
originalPrice Number Used by pricing automation
ignoreAutoPricing Boolean Ignore this day in pricing automation

Retrieve single calendar

[
    {
        "_id": "5e2f1aa0704789001e544e67",
        "date": "2020-05-01",
        "listingId": "5e2f1a94b189e6008fcd8293",
        "status": "unavailable",
        "priceUsd": 1654,
        "accountId": "563e0b6a08a2710e00057b82",
        "lastSyncedAt": "2020-01-28T06:55:09.290Z",
        "note": "",
        "currency": "CAD",
        "blocks": {
            "m": false,
            "r": false,
            "b": false,
            "bd": true,
            "sr": false,
            "abl": false,
            "a": false,
            "bw": false,
            "o": false
        },
        "minNights": 7,
        "price": 10000,
        "notDefaultAvailability": true,
        "isBasePrice": true,
        "listing": {
            "_id": "5e2f1a94b189e6008fcd8293",
            "prices": {
                "currency": "CAD"
            }
        }
    },
    {
        "_id": "5e2f1a9e1593430022ab816d",
        "date": "2020-05-02",
        "listingId": "5e2f1a94b189e6008fcd8293",
        "status": "unavailable",
        "priceUsd": 1654,
        "accountId": "563e0b6a08a2710e00057b82",
        "lastSyncedAt": "2020-01-28T06:55:09.293Z",
        "note": "",
        "currency": "CAD",
        "blocks": {
            "m": false,
            "r": false,
            "b": false,
            "bd": true,
            "sr": false,
            "abl": false,
            "a": false,
            "bw": false,
            "o": false
        },
        "minNights": 7,
        "price": 10000,
        "notDefaultAvailability": true,
        "isBasePrice": true,
        "listing": {
            "_id": "5e2f1a94b189e6008fcd8293",
            "prices": {
                "currency": "CAD"
            }
        }
    },
    {
        "_id": "5e2f1a9f39b941001ed68f10",
        "date": "2020-05-03",
        "listingId": "5e2f1a94b189e6008fcd8293",
        "status": "unavailable",
        "priceUsd": 1654,
        "accountId": "563e0b6a08a2710e00057b82",
        "lastSyncedAt": "2020-01-28T06:55:09.295Z",
        "note": "",
        "currency": "CAD",
        "blocks": {
            "m": false,
            "r": false,
            "b": false,
            "bd": true,
            "sr": false,
            "abl": false,
            "a": false,
            "bw": false,
            "o": false
        },
        "minNights": 7,
        "price": 10000,
        "notDefaultAvailability": true,
        "isBasePrice": true,
        "listing": {
            "_id": "5e2f1a94b189e6008fcd8293",
            "prices": {
                "currency": "CAD"
            }
        }
    },
    {
        "_id": "5e2f1aa1e04b8800237ab257",
        "date": "2020-05-04",
        "listingId": "5e2f1a94b189e6008fcd8293",
        "status": "unavailable",
        "priceUsd": 1654,
        "accountId": "563e0b6a08a2710e00057b82",
        "lastSyncedAt": "2020-01-28T06:55:09.297Z",
        "note": "",
        "currency": "CAD",
        "blocks": {
            "m": false,
            "r": false,
            "b": false,
            "bd": true,
            "sr": false,
            "abl": false,
            "a": false,
            "bw": false,
            "o": false
        },
        "minNights": 7,
        "price": 10000,
        "notDefaultAvailability": true,
        "isBasePrice": true,
        "listing": {
            "_id": "5e2f1a94b189e6008fcd8293",
            "prices": {
                "currency": "CAD"
            }
        }
    },
    {
        "_id": "5e2f1a9d6d808d0022e63c60",
        "date": "2020-05-05",
        "listingId": "5e2f1a94b189e6008fcd8293",
        "status": "unavailable",
        "priceUsd": 1654,
        "accountId": "563e0b6a08a2710e00057b82",
        "lastSyncedAt": "2020-01-28T06:55:09.301Z",
        "note": "",
        "currency": "CAD",
        "blocks": {
            "m": false,
            "r": false,
            "b": false,
            "bd": true,
            "sr": false,
            "abl": false,
            "a": false,
            "bw": false,
            "o": false,
            "an": true
        },
        "minNights": 7,
        "price": 10000,
        "notDefaultAvailability": true,
        "isBasePrice": true,
        "listing": {
            "_id": "5e2f1a94b189e6008fcd8293",
            "prices": {
                "currency": "CAD"
            }
        }
    }
]

HTTP Request

GET /listings/:id/calendar

Query Parameters

Parameter Default Description Example
from Required Return dates starting from this date. Format: YYYY-MM-DD. 2016-01-10
to Required Return dates ending at this date. Format: YYYY-MM-DD. 2016-01-11
minNights false if true, returns the min night value of each day true
fields null Selection of fields, separated by space status

The Block Types

[m] => Manual
[r] => Reserved
[b] => Booked
[bd] => By Default
[sr] => Smart Rules
[abl] => Annual Booking Limit
[a] => Allotment
[bw] => Booking Window
[o] => Owners

Response

Array of calendar day objects

Retrieve multiple calendars

[
    {
        "listingId": "5d64d06ea92d50005b04611c",
        "date": "2020-05-05",
        "status": "available",
        "price": 1,
        "isBasePrice": true,
        "blocks": {
            "m": false,
            "r": false,
            "b": false,
            "bd": false,
            "sr": false,
            "abl": false,
            "a": false,
            "bw": false,
            "o": false
        },
        "rulesApplied": [
            {
                "rule": "repeated days (tuesday)",
                "adjustmentPercentage": -30
            },
            {
                "rule": "minAdjustmentPercentage",
                "adjustmentPercentage": -20
            }
        ],
        "listing": {
            "_id": "5d64d06ea92d50005b04611c",
            "prices": {}
        }
    },
    {
        "listingId": "5d64d06ea92d50005b04611c",
        "date": "2020-05-06",
        "status": "available",
        "price": 1,
        "isBasePrice": true,
        "blocks": {
            "m": false,
            "r": false,
            "b": false,
            "bd": false,
            "sr": false,
            "abl": false,
            "a": false,
            "bw": false,
            "o": false
        },
        "rulesApplied": [
            {
                "rule": "repeated days (wednesday)",
                "adjustmentPercentage": -30
            },
            {
                "rule": "minAdjustmentPercentage",
                "adjustmentPercentage": -20
            }
        ],
        "listing": {
            "_id": "5d64d06ea92d50005b04611c",
            "prices": {}
        }
    },
    {
        "listingId": "5d64d06ea92d50005b04611c",
        "date": "2020-05-07",
        "status": "available",
        "price": 1,
        "isBasePrice": true,
        "blocks": {
            "m": false,
            "r": false,
            "b": false,
            "bd": false,
            "sr": false,
            "abl": false,
            "a": false,
            "bw": false,
            "o": false
        },
        "rulesApplied": [
            {
                "rule": "repeated days (thursday)",
                "adjustmentPercentage": -30
            },
            {
                "rule": "minAdjustmentPercentage",
                "adjustmentPercentage": -20
            }
        ],
        "listing": {
            "_id": "5d64d06ea92d50005b04611c",
            "prices": {}
        }
    },
    {
        "listingId": "5d64d06ea92d50005b04611c",
        "date": "2020-05-08",
        "status": "available",
        "price": 1,
        "isBasePrice": true,
        "blocks": {
            "m": false,
            "r": false,
            "b": false,
            "bd": false,
            "sr": false,
            "abl": false,
            "a": false,
            "bw": false,
            "o": false
        },
        "rulesApplied": [
            {
                "rule": "repeated days (friday)",
                "adjustmentPercentage": 30
            },
            {
                "rule": "maxAdjustmentPercentage",
                "adjustmentPercentage": 20
            }
        ],
        "listing": {
            "_id": "5d64d06ea92d50005b04611c",
            "prices": {}
        }
    },
    {
        "listingId": "5d64d06ea92d50005b04611c",
        "date": "2020-05-09",
        "status": "available",
        "price": 1,
        "isBasePrice": true,
        "blocks": {
            "m": false,
            "r": false,
            "b": false,
            "bd": false,
            "sr": false,
            "abl": false,
            "a": false,
            "bw": false,
            "o": false
        },
        "rulesApplied": [
            {
                "rule": "repeated days (saturday)",
                "adjustmentPercentage": 40
            },
            {
                "rule": "maxAdjustmentPercentage",
                "adjustmentPercentage": 20
            }
        ],
        "listing": {
            "_id": "5d64d06ea92d50005b04611c",
            "prices": {}
        }
    },
    {
        "listingId": "5d64d06ea92d50005b04611c",
        "date": "2020-05-10",
        "status": "available",
        "price": 1,
        "isBasePrice": true,
        "blocks": {
            "m": false,
            "r": false,
            "b": false,
            "bd": false,
            "sr": false,
            "abl": false,
            "a": false,
            "bw": false,
            "o": false
        },
        "rulesApplied": [
            {
                "rule": "repeated days (sunday)",
                "adjustmentPercentage": 40
            },
            {
                "rule": "maxAdjustmentPercentage",
                "adjustmentPercentage": 20
            }
        ],
        "listing": {
            "_id": "5d64d06ea92d50005b04611c",
            "prices": {}
        }
    }
]

HTTP Request

GET /listings/calendars

Query Parameters

Parameter Default Description Example
ids first 10 listings Array of listing ids to return, maximum of 15 listings. ids=5dc1aee9a022cb002029a5c2,ids=5dc1aef496be0d001f388fa7
from Required Return dates starting from this date. Format: yyyy-mm-dd. 2016-01-10
to Required Return dates ending at this date. Format: yyyy-mm-dd. 2016-01-11
minNights false if true, returns the min night value of each day true
fields null Selection of fields, separated by space. use minNights to return the min nights per day status minNights

Example Call

https://api.guesty.com/api/v2/listings/calendars?ids=5dc1aee9a022cb002029a5c2&ids=5dc1aef496be0d001f388fa7&ids=5de0599ad373bc001e0e0c11&ids=5defc258eaed8f001fda8caf&ids=5df1b0b1bd3702001e9fbb3c&ids=5df1bd01685c34001f3c8049&ids=5e16853755624f001f018e6b&ids=5dfc18e1df04d9001f7a4426&ids=5ddfee774d488f001ee48227&ids=5e18d2055cc00c0021a0e7d0&ids=5de084f33bdf86001efc1039&ids=5df86d70c762b3002372bdae&ids=5e0cc60e2ff5de0023fe281b&ids=5e13eff05a2f0e001f946b35&ids=5df99d93716cfa0022cbe5ef&from=2022-09-24&to=2022-09-24&fields=status

Response

Object of calendar ids, where each id is an array of day objects.

Update calendars

HTTP Request

PUT /listings/calendars

Body Parameters

Parameter Default Description Example
listings Required Array of ids of listings to update, or a single id. ``
from Required Update dates starting from this date. Format: yyyy-mm-dd. "2016-01-10"
to Required Update dates ending at this date. Format: yyyy-mm-dd. "2016-01-11"
status --- New status, enum: available, unavailable. available
price --- New price, in the listing's currency. 100
minNights Number New min nights value" '2'
note --- Note to add to those dates.

The API can recieve an array with the above params for multiple listing and days update, example: [{"listingId":"LISTINGID1","from":"2020-01-13","to":"2020-01-16","price":70},{"listingId":"LISTINGID1","from":"2020-04-17","to":"2020-04-18","price":75},{"listingId":"LISTINGID2","from":"2020-03-19","to":"2020-03-23","price":70}]

Response

OK

Reservations

The reservation object

{
    "_id": "595fe29f4ab86112341425ac",
    "daysInAdvance": 39,
    "accountId": "55b9f9b5393dfe0e0023455d",
    "listingId": "582df199dd162a040123542",
    "guestId": "595fe29c4ab861100023423a",
    "status": "confirmed",
    "confirmationCode": "EXAMPLE",
    "checkInDateLocalized": "2017-08-16",
    "checkOutDateLocalized": "2017-08-28",
    "guestsCount": 2,
    "source": "Booking.com",
    "checkIn": "2017-08-16T13:00:00.000Z",
    "checkOut": "2017-08-28T09:00:00.000Z",
    "nightsCount": 12,
    "confirmedAt": "2017-07-07T19:35:59.896Z",
    "keyCode": "12345",
    "customFields": [
        {
            "fieldId": "57569cf62ed4400e001678fa",
            "value": "New",
            "_id": "595fe2a04ab8611000a525b0"
        }
    ],
    "log": [
        {
            "event": "Reservation was updated",
            "by": "Me",
            "_id": "595fe9660b9b6e10001649d2",
            "changes": [
                {
                    "field": "customFields 1 _id",
                    "_id": "595fe9660b9b6e10001649e5",
                    "diff": [
                        {
                            "value": "595fe9650b9b6e10001649d1",
                            "added": true,
                            "_id": "595fe9660b9b6e10001649e6"
                        }
                    ]
                }
            ],
            "at": "2017-07-07T20:04:54.058Z"
        }
    ],
    "review": {
        "shouldReview": true
    },
    "money": {
        "currency": "EUR",
        "hostPayout": 1119,
        "guestTotalPrice": 1119,
        "alreadyPaid": 0,
        "fareAccommodation": 1079,
        "fareCleaning": 40,
        "ownerRevenue": 718.5,
        "commissionIncTax": 214.5,
        "commissionTax": 37.23,
        "commissionTaxPercentage": 21,
        "commission": 177.27,
        "commissionFormula": "net_income + 50",
        "netIncome": 933,
        "netIncomeFormula": "round(host_payout+fare_cleaning)",
        "isFullyPaid": false,
        "balanceDue": 1119,
        "paymentsDue": 0,
        "totalPaid": 0,
        "totalRefunded": 0,
        "subTotalPrice": 1119,
        "hostPayoutUsd": 1301.786437223414,
        "autoPaymentsPolicy": [],
        "payments": [],
        "invoiceItems": [
            {
                "title": "Accommodation fare",
                "amount": 1079,
                "currency": "EUR",
                "isLocked": true,
                "_id": "595fe29f4ab8611000a525ad"
            },
            {
                "title": "Additional invoice item (optional)",
                "amount": 10,
                "currency": "EUR",
                "type": "MANUAL",
                "_id": "595fe29f4ab8611000a525a1"
            }
        ]
    },
    "integration": {
        "_id": "56cd9ab369a2100e00742341",
        "platform": "rentalsUnited",
        "rentalsUnited": {
            "id": 129132421,
            "listingId": 98920,
            "channelReservationId": "1906924521"
        }
    },
    "createdAt": "2017-07-07T19:35:59.900Z",
    "plannedArrival": "15:00",
    "plannedDeparture": "8:00",
    "listing": {
        "_id": "582df199dd162a04002c0693",
        "title": "Industrial and Minimal Mansion",
        "address": {
            "full": "The full address"
        },
        "picture": {
            "thumbnail": "//guestybookings.s3.amazonaws.com/listings/thumbnail_234161096.jpg"
        },
        "nickname": "nickname example"
    },
    "guest": {
        "_id": "595fe29c4ab8611000a525aa",
        "email": "example@example.com",
        "hometown": "76 grand drive City: auckland",
        "fullName": "Sara Duma",
        "phone": "447537986159",
        "picture": {}
    }
}
Attribute Type Description
_id String Unique id
accountId String (ObjectId)
listingId String (ObjectId)
createdAt Date
lastUpdatedAt Date
closedAt Date
confirmedAt Date
alteredAt Date
canceledAt Date
keyCode String Keycode for the reservation
canceledBy String
importedAt Date
integration integration Object (see below)
status Enum inquiry, declined, expired, canceled, closed, reserved, confirmed, checked_in, checked_out, awaiting_payment
confirmationCode String
checkIn Date
checkInDateLocalized String
checkOut Date
checkOutDateLocalized String
plannedArrival String Planned time of arrival: HH:mm
plannedDeparture String Planned time of departure: HH:mm
nightsCount Number
daysInAdvance Number
guestsCount Number
cancellationPolicy String
instantBook Boolean
guestId String (ObjectId)
isReturningGuest Boolean
money money Object (see below)
review review Object (see below)
notes notes Object (see below)
log log Object (see below)
source String The source of the reservation
customFields [customFields Object] (see below)

The integration object

Attribute Type Description
_id String
platform Enum airbnb, rentalsUnited, manual, bookingCom or homeaway (in development)
airbnb object Details related to Airbnb (id, listingId, guestId)
rentalsUnited Object Details related to RU (id, listingId)
bookingCom Object Details related to bookingCom (id, listingId, reservationId)
homeAway Object Coming soon!

The money object

Attribute Type Description
currency String
fareAccommodation Number
fareCleaning Number
subTotalPrice Number
guestServiceFee Number
guestTaxes Number
guestTotalPrice Number
alreadyPaid Number
hostServiceFee Number
hostTaxes Number
hostPayout Number
hostPayoutUsd Number
hostOriginalPayout Number if reservation is canceled.
netIncomeFormula String
netIncome Number
commissionFormula String
commission Number
commissionTaxPercentage Number
commissionTax Number
commissionIncTax Number
ownerRevenue Number
invoiceItems [invoiceItems] (see below)
payments [payments] (see below)

The payment object

{
    "receiptId": 14464234,
    "paymentMethodId": "58a48a4fea2a13ea9fda5873",
    "guestId": "59a0cccb9437ed04001fa6df",
    "confirmationCode": "194017946",
    "amount": 1347,
    "currency": "GBP",
    "shouldBePaidAt": "2017-08-03T13:00:00.000Z",
    "paidAt": "2017-08-03T13:00:00.000Z",
    "_id": "59a24239a992940400fd8e49",
    "receiptTargets": [],
    "attempts": [],
    "createdAt": "2017-08-27T03:53:29.142Z",
    "refunds": [],
    "status": "SUCCEEDED"
}
Attribute Type Description
paymentMethodId String (ObjectId)
status String
refunds [refunds]
---amount Number
---createdAt Date
---status String
---note String
guestId String (ObjectId)
confirmationCode String
amount Number
currency Enum
createdAt Date
shouldBePaidAt Date
paidAt Date
attempts [attempts]
---createdAt Date
---status String
---payload Object attempt payload
---error

The invoiceItems object

Attribute Type Description
title String
amount Number
currency String
isLocked Boolean
type Enum TAX, CLEANING_FEE, PET_FEE, ADDITIONAL, UNKNOWN, OTHER, MANUAL, CANCELLATION_FEE, GUEST_FEE, ACTIVITY, DEPOSIT, MISC, PROTECTION, ACCOMMODATION_FARE, DISCOUNT

The review object

{
    "shouldReview" : true,
    "hostReview" : {
        "createdAt" : "2017-08-27T03:53:24.535Z",
        "public" : "Anies was the perfect guest and we can recommend to other owners without hesitation. We hope we get the opportunity to host them again in the future. Many thanks, Will&Team."
    },
    "hasGuestReviewed" : true,
    "guestReview" : {
        "public" : "The place is very clean. A nice high-ceilinged open-plan flat with huge living area and a modern kitchen. Walking distance to Angel and Exmouth Market. My parents and I had an enjoyable stay there.",
        "private" : "",
        "createdAt" : "2017-08-27T03:53:25.821Z"
    }
}
Attribute Type Description
shouldReview Boolean deprecated
hostReview
guestReview
hasGuestReviewed
expiresAt

The notes object

Attribute Type Description
cleaning String
guest String
other String

The customFields object

Attribute Type Description
fieldId ObjectId Ref to the definition (account.customFields._id)
value Mixed Type is according to the definition

The log object

{
    "event": "Reservation was updated",
    "by": "Me",
    "_id": "595fe9660b9b6e10001649d2",
    "changes": [
        {
            "field": "customFields 1 _id",
            "_id": "595fe9660b9b6e10001649e5",
            "diff": [
                {
                    "value": "595fe9650b9b6e10001649d1",
                    "added": true,
                    "_id": "595fe9660b9b6e10001649e6"
                }
            ]
        }
    ],
    "at": "2017-07-07T20:04:54.058Z"
}
Attribute Type Description
event String
description String
by String
at Date
changes [changes]
---fields String
---diff [diff]
------- value String
------- added Boolean
------- removed Boolean

Create a reservation

Response

{
    "__v": 0,
    "lastUpdatedAt": "2017-09-13T14:31:37.460Z",
    "listingId": "59b928bb8e6bb31000219e58",
    "checkInDateLocalized": "2017-09-15",
    "checkOutDateLocalized": "2017-09-18",
    "status": "inquiry",
    "accountId": "563e0b6a08a2710e00057b82",
    "guestId": "59b9414932123a1000b7cd54",
    "guestsCount": 1,
    "source": "Manual",
    "checkIn": "2017-09-15T12:00:00.000Z",
    "checkOut": "2017-09-18T08:00:00.000Z",
    "nightsCount": 3,
    "checkInIsFlexible": true,
    "checkOutIsFlexible": true,
    "_id": "59b9414932123a1000b7cd55",
    "customFields": [],
    "confirmedPreBookings": [],
    "log": [],
    "pendingTasks": [],
    "review": {
        "shouldReview": true
    },
    "money": {
        "ownerRevenue": 450,
        "commissionIncTax": 50,
        "commissionTax": 0,
        "commissionTaxPercentage": 0,
        "commission": 50,
        "commissionFormula": "net_income*0.1",
        "netIncome": 500,
        "netIncomeFormula": "host_payout",
        "isFullyPaid": false,
        "balanceDue": 500,
        "paymentsDue": 0,
        "totalPaid": 0,
        "totalRefunded": 0,
        "fareAccommodation": 500,
        "currency": "USD",
        "hostPayout": 500,
        "subTotalPrice": 500,
        "hostPayoutUsd": 500,
        "autoPaymentsPolicy": [],
        "payments": [],
        "invoiceItems": [
            {
                "title": "Accommodation fare",
                "amount": 500,
                "currency": "USD",
                "isLocked": true,
                "_id": "59b9414932123a1000b7cd56"
            }
        ]
    },
    "integration": {
        "_id": "5784a3cc64ce9c0e00ecaf1e",
        "platform": "manual",
        "limitations": {
            "availableStatuses": []
        }
    },
    "createdAt": "2017-09-13T14:31:37.452Z",
    "id": "59b9414932123a1000b7cd55"
}

HTTP Request

POST /reservations

Validations

The field money.invoiceItems is optional. But if it exists in request body, the field money.invoiceItems.type is required for every invoice item.

Body

Parameter Default
listingId Required
checkInDateLocalized Required
checkOutDateLocalized Required
status Required
money Required
---fareAccommodation Required
---fareCleaning Optional
---guestTaxes Optional
---currency Required
---invoiceItems Optional
-------type
guestId Either ID or Details
guest See Below
---firstName
---lastName
---email
---phone

Guest

There are two options for defining guest.

1) Pass the guestId property. If a gest exists with the given ID it will be attached to the reservation. If there is no guest with such ID "Guest not found" error will be returned. Please note that if you use separate endpoint to create guest first, it will take some time before it is available for reading because we use separate clusters for read and write operations.

2) Pass the guest object. You can define guest right in "create reservation" request. The guest will be automatically created and attached to reservation. If you send the same object next time it will be matched to existing and it will not create a duplicate.

You shouldn't pass both properties at the same time. If you don't pass any of the properties, a guest will be created without any info. But it will still be attached to your account/apiKey.

Validations

System will make sure reservation is according to terms (min, max nights, any other terms), and decline otherwise (401), unless flag (ignoreTerms). System will make sure calendar is available, and decline otherwise (401), unless flag (ignoreCalendar).

Example

Body

{"listingId": "59b928bb8e6bb31000219e58", "checkInDateLocalized": "2017-09-15", "checkOutDateLocalized": "2017-09-18", "status": "inquiry", "money":{"fareAccommodation": "500", "currency": "USD"}, "guest":{"firstName": "Tony", "lastName"": "Stark", "phone": "+7777777", "email": "tony@stark.com"}}

Response

The inserted object.

Retrieve a reservation

HTTP Request

GET /reservations/:id

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space. When null retrieve the main properties of the object. We recommend always specifying the specific fields you'd like to receive to ensure that you get them. Please see the full list above. checkIn status

Response

Reservation object

Update a reservation

HTTP Request

PUT /reservations/:id

Body

Selected fields to update.

limitations; checkIn and checkOut can not be amended, in order to update these values, please use checkInDateLocalized and plannedArrival in order to amened check in details and checkOutDateLocalized and plannedDeparture to update check out details.

Validations: The System will make sure reservation is according to terms (min, max nights, any other terms), and decline otherwise (401), unless flag (ignoreTerms=true). The System will make sure calendar is available, and decline otherwise (401), unless flag (ignoreCalendar=true).

Response

Retrieve the updated reservation, selection of fields that were sent in body.

Add a payment for reservation

HTTP Request

POST /reservations/:id/payments

Body

Parameter Default Description
paymentMethod Required
---method Required 'CASH','CREDIT','DEBIT','ECHECK','STRIPE'
---_id Required if method is "STRIPE"
amount
shouldBePaidAt
paidAt
note
creditCard Required if method is "STRIPE"

Example

Body

{ "amount": 10, "shouldBePaidAt": "2020-05-19T17:36:58.600Z", "creditCard": "paymentMethodId", "paymentMethod": { "method": "STRIPE", "saveForFutureUse": true, "_id": "paymentMethodId" } }

Response

Retrieve the updated reservation, selection of money.payments field.

Update an existing payment

HTTP Request

PUT /reservations/:id/payments

Body

Parameter Default Description
paymentId Required the _id of the payment to update
paymentMethod Required
---method Required 'CASH','CREDIT','DEBIT','ECHECK','STRIPE'
---_id
amount
shouldBePaidAt
paidAt
note
stripePaymentMethodToken

Example

Body

{"paymentId": "5ea809dbef629f00311ee947","paymentMethod": {"method": "STRIPE"}}

Response

Retrieve the updated reservation, selection of money.payments field.

Cancel an existing payment

HTTP Request

PUT /reservations/:id/payments/:paymentId

Body

Parameter Default Description
paymentId Required the _id of the payment to cancel
paymentMethod Required
---method Required 'CASH','CREDIT','DEBIT','ECHECK','STRIPE'
---_id Required
status Required "CANCELLED"

Example

Body

{ "paymentId": "5d80c3254c650a001faacdb4", "paymentMethod": { "_id": "589894a91d756b9c47ce1e87", "method": "CASH" }, "status":"CANCELLED"

Response

Retrieve the updated payments object with the updated status.

{
    "_id": "5884ebaaded55810009bb38a",
    "money": {
        "payments": [
            {
                "paymentMethodStatus": "ACTIVE",
                "isAuthorizationHold": false,
                "status": "CANCELLED",
                "refunds": [
                    {
                        "createdAt": "2019-07-23T18:27:24.052Z",
                        "_id": "5d37518c029c950021095f10",
                        "amount": 200,
                        "status": "SUCCEEDED"
                    }
                ],
                "authorizationHoldCaptures": [],
                "createdAt": "2019-07-23T18:27:04.928Z",
                "attempts": [],
                "receiptTargets": [
                    {
                        "sentAt": [
                            "2020-04-19T20:36:55.638Z"
                        ],
                        "_id": "5e9cb667972321002be33411",
                        "email": "allan@guesty.com"
                    }
                ],
                "_id": "5d3751785007c70020938d34",
                "amount": 200,
                "paymentMethodId": "589894a91d756b9c47ce1e87",
                "guestId": "58517197f0a29b1000a38053",
                "currency": "USD",
                "shouldBePaidAt": "2019-07-23T18:27:04.928Z",
                "paidAt": "2019-07-23T18:27:04.928Z",
                "receiptId": 17280128,
                "guest": {
                    "_id": "58517197f0a29b1000a38053",
                    "email": "aviad_14@guesty.com",
                    "fullName": "Aryah Stark"
                },
                "paymentMethod": {
                    "_id": "589894a91d756b9c47ce1e87",
                    "method": "CASH"
                }
            },
            {
                "paymentMethodStatus": "ACTIVE",
                "isAuthorizationHold": false,
                "status": "CANCELLED",
                "_id": "5d80c3254c650a001faacdb4",
                "refunds": [],
                "authorizationHoldCaptures": [],
                "createdAt": "2019-09-17T11:27:33.757Z",
                "attempts": [],
                "receiptTargets": [],
                "amount": 100,
                "paymentMethodId": "589894a91d756b9c47ce1e87",
                "guestId": "58517197f0a29b1000a38053",
                "currency": "USD",
                "shouldBePaidAt": "2019-09-17T11:27:33.757Z",
                "paidAt": "2019-09-17T11:27:33.757Z",
                "receiptId": 17497347,
                "guest": {
                    "_id": "58517197f0a29b1000a38053",
                    "email": "aviad_14@guesty.com",
                    "fullName": "Aryah Stark"
                },
                "paymentMethod": {
                    "_id": "589894a91d756b9c47ce1e87",
                    "method": "CASH"
                }
            },
            {
                "paymentMethodStatus": "ACTIVE",
                "isAuthorizationHold": false,
                "status": "SUCCEEDED",
                "refunds": [],
                "authorizationHoldCaptures": [],
                "createdAt": "2020-04-14T20:59:10.144Z",
                "attempts": [],
                "receiptTargets": [],
                "_id": "5e96241efdd1c00029651b91",
                "amount": 128.73,
                "paymentMethodId": "589894a91d756b9c47ce1e87",
                "guestId": "58517197f0a29b1000a38053",
                "currency": "USD",
                "shouldBePaidAt": "2020-04-14T20:59:10.086Z",
                "paidAt": "2020-04-14T20:59:10.086Z",
                "receiptId": 18299424,
                "guest": {
                    "_id": "58517197f0a29b1000a38053",
                    "email": "aviad_14@guesty.com",
                    "fullName": "Aryah Stark"
                },
                "paymentMethod": {
                    "_id": "589894a91d756b9c47ce1e87",
                    "method": "CASH"
                }
            }
        ]
    }
}

Add an new Invoice item

HTTP Request

POST /reservations/:id/invoiceItems

Body

Parameter Default Description
title Required name to be displayed
amount Required amount to be add
description Required a short description (may be "")

Response

Retrieve the updated reservation, selection of money.payments field.

Search reservations

{
     "count": 3,
     "limit": 25,
     "skip": 0,
     "results": [
        {
            "_id" : "5655b3dec03ca814016a5038",
            "createdAt" : "2014-12-17T08:33:44.510Z",
            "integration" : {
                "platform" : "airbnb",
                "_id" : "53eb27386b51b257846cdd11",
                "airbnb" : {
                    "listingId" : 1148991,
                    "guestId" : 3648962
                }
            },
            "status" : "inquiry",
            "guestId" : "5655b3debf1fab1507921c33",
            "listingId" : "5319674d4930a7f09b075696",
            "checkIn" : "2013-11-21T22:00:00.000Z",
            "checkOut" : "2013-11-26T22:00:00.000Z",
            "checkInDateLocalized" : "2013-11-22",
            "checkOutDateLocalized" : "2013-11-27",
            "guestsCount" : 1,
            "money" : {
                "ourCommission" : 0,
                "ownerRevenue" : 0.0,
                "userRevenue" : 0,
                "userRevenueFormula" : "host_payout",
                "netIncome" : 0,
                "netIncomeFormula" : "fare_accommodation + fare_cleaning",
                "commission" : 0,
                "commissionFormula" : "net_income*0.2",
                "commissionIncTax" : 0,
                "commissionTax" : 0,
                "commissionTaxPercentage" : 16
            },
            "accountId" : "5319674d4930a7f09b075695",
            "source" : "Airbnb",
            "lastUpdatedAt" : "2016-04-19T19:50:54.292Z"
        }
     ]
}

HTTP Request

GET /reservations

Query Parameters

Parameter Default Description Example
viewId null Pull a specific view (view is a saved settings of accountId, filters, fields, sort) 556d95083c59ae58e3fdd8f4
filters [{"field":"status", "operator":"$in", "value":["confirmed"]},{"field":"checkIn", "operator":"$gt", "context":"now", "value":0}] Array of filters to query by (See below) See default
fields checkIn checkOut confirmationCode guest.fullname listing.title Selection of fields, separated by space See default
sort checkIn The field to sort by. Preppend - for DESC. checkIn/-checkIn
limit 25 Pagination 25
skip 0 Pagination 0

Filters

{
    "field": "checkIn",
    "operator": "$gt",
    "value": 0,
    "context": "now"
}
Parameter Default Description Example
field Required Subject of the filter
operator Required Enhanced MongoDB comparison operator: $eq, $not, $contains, $notcontains, $gt, $lt, $between
value Required Value to filter by.
context null Optional preprocessing. Options are now, createdAt, confirmedAt, canceledAt, alteredAt. When given, the date in value is relative to the context.

Response

Reservation objects

Export as CSV

HTTP Request

GET /reservations.csv

Same as /reservations but results are returned as a downloadable csv file

Send results in email

HTTP Request

POST /reservations.email

Same as /reservations but results are sent as an email

Body Parameters

Parameter Default Description Example
to Required Address of recipient koby@guesty.com

Approve a pending booking request

{
    "status": "confirmed",
    "_id": "5a7306914976200093ee9ebf"
}

HTTP Request

POST /reservations/:id/approve

Response

Reservation object - _id and status fields.

Decline a pending booking request

{
    "status": "declined",
    "_id": "5a7307182ffb49005b0bff9a"
}

HTTP Request

POST /reservations/:id/decline

Response

Reservation object - _id and status fields.

Get all reservation's custom fields

HTTP Request

GET /reservations/:Id/custom-fields/

Get a reservation's custom field

HTTP Request

GET /reservations/:Id/custom-fields/{field_id}

Update Reservation's Custom Fields

HTTP Request

PUT /reservations/{reservation_id}/custom-fields/

Body

{ "customFields": [ { "fieldId": "your_field_id", "value": 3 }, { "fieldId": "your_field_id", "value": "london apartment" }, { "fieldId": "your_field_id", "value": "wifipassword" } ] } Parameter | Default | Description | Example --------- | ------- | ----------- | ------- fieldId | Requiered | ------- | 5f744b491af840002ca636a2 value | required | The text field name | "wifipassword"

Response

The updated object.

Delete Reservation's Custom Fields

HTTP Request

DELETE /reservations/{reservation_id}/custom-fields/{{field_id}}

Owners Reservations

The owners-reservations object

{
    "_id": "5e6a2110ec00800028ede79e",
    "status": "confirmed",
    "source": "owners portal",
    "ownerId": "5dc1794a6aed080024e50521",
    "accountId": "596f6fe706112710005d96ff",
    "listingId": "5988346d3c31bf0f00747eb6",
    "checkIn": "2020-03-19 15:00:00",
    "checkOut": "2020-03-20 10:00:00",
    "note": "test note",
    "createdAt": "2020-03-12T11:46:24.118Z",
    "__v": 0,
    "id": "5e6a2110ec00800028ede79e"
}
Attribute Type Description
_id String Unique id
status Enum inquiry, declined, expired, canceled, closed, reserved, confirmed, checked_in, checked_out, awaiting_payment
source String
ownerId String ObjectId
accountId String ObjectId
listingId String ObjectId
checkIn String YYYY-MM-DD HH:MM:SS
checkOut String YYYY-MM-DD HH:MM:SS
note String
createdAt Date ISO
__v Number
id String Unique id

The owners-reservations full object

{
    "status": "canceled",
    "source": "owners portal",
    "_id": "5e6a28e32275770029393bac",
    "ownerId": "5dc1794a6aed080024e50521",
    "accountId": "596f6fe706112710005d96ff",
    "listingId": "5988346d3c31bf0f00747eb6",
    "checkIn": "2020-03-17 15:00:00",
    "checkOut": "2020-03-18 10:00:00",
    "createdAt": "2020-03-12T12:19:47.812Z",
    "__v": 1,
    "checkInDateLocalized": "Mar 17, 2020",
    "checkOutDateLocalized": "Mar 18, 2020",
    "lastUpdatedAt": "2020-03-12T12:19:47.824Z",
    "listing": {
        "address": {
            "street": "Place Cendrillon",
            "zipcode": "78280",
            "lng": 2.0753368,
            "lat": 48.7747508,
            "country": "France",
            "state": "Île-de-France",
            "city": "Guyancourt",
            "full": "Place Cendrillon, 78280 Guyancourt, France",
            "searchable": "Guyancourt, Île-de-France, France"
        },
        "tags": [
            "dungeon",
            "aviv"
        ],
        "_id": "5988346d3c31bf0f00747eb6",
        "bathrooms": 1,
        "title": "my castle 1 test property",
        "bedrooms": 1,
        "accommodates": 4,
        "propertyType": "Apartment",
        "roomType": "Entire home/apt",
        "beds": 1,
        "nickname": "my private dungeon12",
        "areaSquareFeet": 12
    },
    "nightsCount": 1,
    "note": "",
    "ownerId": {
        "locale": "en-US",
        "_id": "5dc1794a6aed080024e50521",
        "email": "test@test.com",
        "fullName": "test test"
    },
    "plannedArrival": "03:00 PM",
    "plannedDeparture": "10:00 AM",
    "canceledAt": "2020-03-12T12:20:05.741Z",
    "id": "5e6a28e32275770029393bac"
}
Attribute Type Description
_id String Unique id
status Enum confirmed, checked_in, checked_out, inquiry, declined, canceled, closed
source String
ownerId String ObjectId
accountId String ObjectId
listingId String ObjectId
checkIn String
checkOut String
createdAt Date ISO
__v Number
checkInDateLocalized String
checkOutDateLocalized String
lastUpdatedAt Date ISO
listing ListingInfo object
nightsCount Number
note String
owner OwnerInfo object
plannedArrival String Planned time of arrival: HH:mm
plannedDeparture String Planned time of arrival: HH:mm
cancelledAt Date ISO
id String Unique id

The OwnerInfo object

{
    "locale": "en-US",
    "_id": "5dc1794a6aed080024e50521",
    "email": "test@test.com",
    "fullName": "test test"
}
Attribute Type Description
_id String ObjectId
locale String
email String
fullName String

The ListingInfo object

{
    "address": {
        "street": "Place Cendrillon",
        "zipcode": "78280",
        "lng": 2.0753368,
        "lat": 48.7747508,
        "country": "France",
        "state": "Île-de-France",
        "city": "Guyancourt",
        "full": "Place Cendrillon, 78280 Guyancourt, France",
        "searchable": "Guyancourt, Île-de-France, France"
    },
    "tags": [
        "dungeon",
        "aviv"
    ],
    "_id": "5988346d3c31bf0f00747eb6",
    "bathrooms": 1,
    "title": "my castle 1 test property",
    "bedrooms": 1,
    "accommodates": 4,
    "propertyType": "Apartment",
    "roomType": "Entire home/apt",
    "beds": 1,
    "nickname": "my private dungeon12",
    "areaSquareFeet": 12
}
Attribute Type Description
_id String Unique id
bathrooms Number
title String
bedrooms Number
accomodates Number
propertyType String
roomType String
beds Number
nickname String
areaSquareFeet Number
address ListingAddress object
tags [String]

The ListingAddress object

{
    "street": "Place Cendrillon",
    "zipcode": "78280",
    "lng": 2.0753368,
    "lat": 48.7747508,
    "country": "France",
    "state": "Île-de-France",
    "city": "Guyancourt",
    "full": "Place Cendrillon, 78280 Guyancourt, France",
    "searchable": "Guyancourt, Île-de-France, France"
}
Attribute Type Description
full String
city String
state String
country String
zipcode String
neighborhood String
street String
apt String
lat Number
lng Number
searchable String
floor Number

List owners-reservations

{
    "results": [
        {
            "status": "canceled",
            "source": "owners portal",
            "_id": "5e6a28e32275770029393bac",
            "ownerId": "5dc1794a6aed080024e50521",
            "accountId": "596f6fe706112710005d96ff",
            "listingId": "5988346d3c31bf0f00747eb6",
            "checkIn": "2020-03-17 15:00:00",
            "checkOut": "2020-03-18 10:00:00",
            "createdAt": "2020-03-12T12:19:47.812Z",
            "__v": 1,
            "checkInDateLocalized": "Mar 17, 2020",
            "checkOutDateLocalized": "Mar 18, 2020",
            "lastUpdatedAt": "2020-03-12T12:19:47.824Z",
            "listing": {
                "address": {
                    "street": "Place Cendrillon",
                    "zipcode": "78280",
                    "lng": 2.0753368,
                    "lat": 48.7747508,
                    "country": "France",
                    "state": "Île-de-France",
                    "city": "Guyancourt",
                    "full": "Place Cendrillon, 78280 Guyancourt, France",
                    "searchable": "Guyancourt, Île-de-France, France"
                },
                "tags": [
                    "dungeon",
                    "aviv"
                ],
                "_id": "5988346d3c31bf0f00747eb6",
                "bathrooms": 1,
                "title": "my castle 1 test property",
                "bedrooms": 1,
                "accommodates": 4,
                "propertyType": "Apartment",
                "roomType": "Entire home/apt",
                "beds": 1,
                "nickname": "my private dungeon12",
                "areaSquareFeet": 12
            },
            "nightsCount": 1,
            "note": "",
            "ownerId": {
                "locale": "en-US",
                "_id": "5dc1794a6aed080024e50521",
                "email": "test@test.com",
                "fullName": "test test"
            },
            "plannedArrival": "03:00 PM",
            "plannedDeparture": "10:00 AM",
            "canceledAt": "2020-03-12T12:20:05.741Z",
            "id": "5e6a28e32275770029393bac"
        }
    ],
    "title": "Bookings Report",
    "count": 1,
    "fields": "checkIn checkOut owner.fullName listing.title",
    "limit": 25,
    "skip": 0
}

HTTP Request

GET /owners-reservations

Response

Reservation Object

Query Parameters

Parameter Default Description
fields checkIn checkOut owner.fullName listing.title String of Fields
filters [{"field":"status", "operator":"$eq", "value":"confirmed"}, Array of Filters
{"field":"checkIn", "operator":"$gt", "context":"now", "value":0}]
sort checkIn ascending sort , use - to descending sort
limit 25 Limit results
skip 0 skip results

Fields

"account.name listing.title listing.address.full owner owner.pictures.thumbnail"
Parameter Key Sub key Description
account AccountKeys AccountSubKey String of Account object keys
listing ListingKeys ListingSubKey String of Listing object keys
owner OwnerKeys OwnerSubKey String of Owner object keys

Filters

Parameter Default Description Example
field Required Subject of the filter (see bellow)
operator Required Enhanced MongoDB comparison operator: $eq, $not, $contains, etc.
value Required Value to filter by.
Parameter Format Example
confirmedAt YYYY-MM-DD
checkIn YYYY-MM-DD
checkOut YYYY-MM-DD
customFields customFields.fieldName
owner owner.fieldName owner._id
listing listing.fieldName listing.nickname

Retrieve an owner reservation

HTTP Request

GET /owners-reservations/:id

Response

Reservation Object

Update owner reservation

HTTP Request

PUT /owners-reservations/:id

Validations

Body

Parameter Default
checkIn Required
checkOut Required
note Optional

Example

Body

{ "checkIn": "2020-03-19 15:00:00", "checkOut": "2020-03-20 10:00:00", "note": "test message" }

Response

{
    "ownerReservation": {
        "status": "confirmed",
        "source": "owners portal",
        "_id": "5e6a2110ec00800028ede79e",
        "ownerId": {
            "forgotPassword": {
                "expiresAt": "2020-02-06T13:00:53.623Z",
                "hash": "5958fa55712ce6ccef8e715e9e6c17f365900c328fde474755d23d5788331252b044e9da3896ce5e8f4872712913562e"
            },
            "ownersPortalSettings": {
                "bookedNights": true,
                "revenue": true
            },
            "listings": [
                "5988346d3c31bf0f00747eb6"
            ],
            "locale": "en-US",
            "active": true,
            "allowReservations": true,
            "showReservationTooltips": true,
            "workingCapital": 0,
            "_id": "5dc1794a6aed080024e50521",
            "accountId": "596f6fe706112710005d96ff",
            "firstName": "test_owner_from_listing_admin_k",
            "lastName": "test_owner_from_listing_admin_m",
            "email": "hyperstan@ukr.net",
            "createdAt": "2019-11-05T13:29:46.389Z",
            "fullName": "test_owner_from_listing_admin_k test_owner_from_listing_admin_m",
            "__v": 3
        },
        "accountId": "596f6fe706112710005d96ff",
        "listingId": "5988346d3c31bf0f00747eb6",
        "checkIn": "2020-03-19 15:00:00",
        "checkOut": "2020-03-21 10:00:00",
        "note": "test message",
        "createdAt": "2020-03-12T11:46:24.118Z",
        "__v": 0,
        "checkInDateLocalized": "Mar 19, 2020",
        "checkOutDateLocalized": "Mar 21, 2020",
        "lastUpdatedAt": "2020-03-12T13:06:46.618Z",
        "listing": {
            "address": {
                "street": "Place Cendrillon",
                "zipcode": "78280",
                "lng": 2.0753368,
                "lat": 48.7747508,
                "country": "France",
                "state": "Île-de-France",
                "city": "Guyancourt",
                "full": "Place Cendrillon, 78280 Guyancourt, France",
                "searchable": "Guyancourt, Île-de-France, France"
            },
            "tags": [
                "dungeon",
                "aviv"
            ],
            "_id": "5988346d3c31bf0f00747eb6",
            "bathrooms": 1,
            "title": "my castle 1 test property",
            "bedrooms": 1,
            "accommodates": 4,
            "propertyType": "Apartment",
            "roomType": "Entire home/apt",
            "beds": 1,
            "nickname": "my private dungeon12",
            "areaSquareFeet": 12
        },
        "nightsCount": 2,
        "ownerId": {
            "locale": "en-US",
            "_id": "5dc1794a6aed080024e50521",
            "email": "hyperstan@ukr.net",
            "fullName": "test_owner_from_listing_admin_k test_owner_from_listing_admin_m"
        },
        "plannedArrival": "03:00 PM",
        "plannedDeparture": "10:00 AM",
        "id": "5e6a2110ec00800028ede79e"
    },
    "conversation": {
        "meta": {
            "reservations": []
        },
        "language": "en",
        "isRead": false,
        "priority": 10,
        "snoozedUntil": null,
        "_id": "5e6a2110ec00800028ede7a0",
        "accountId": "596f6fe706112710005d96ff",
        "conversationWith": "owner",
        "ownerId": "5dc1794a6aed080024e50521",
        "ownerReservationId": "5e6a2110ec00800028ede79e",
        "pendingTasks": [],
        "createdAt": "2020-03-12T11:46:24.231Z",
        "thread": [
            {
                "_id": "5e6a35152275770029395bff",
                "createdAt": "2020-03-12T13:11:49.186Z",
                "module": "portal",
                "type": "fromOwner",
                "body": "test message",
                "attachments": [],
                "id": "5e6a35152275770029395bff"
            },
            {
                "createdAt": "2020-03-12T13:06:46.628Z",
                "attachments": [],
                "_id": "5e6a33e62275770029395855",
                "module": "note",
                "type": "fromOwner",
                "body": "test_owner_from_listing_admin_k test_owner_from_listing_admin_m updated the reservation at my private dungeon12 to be from Mar 19, 2020 at 03:00 PM\n\t\t\t\t\tuntil Mar 21, 2020 at 10:00 AM",
                "id": "5e6a33e62275770029395855"
            },
            {
                "createdAt": "2020-03-12T13:06:46.628Z",
                "attachments": [],
                "_id": "5e6a33e62275770029395857",
                "module": "portal",
                "type": "fromOwner",
                "body": "test message",
                "id": "5e6a33e62275770029395857"
            },
            {
                "createdAt": "2020-03-12T11:46:24.232Z",
                "attachments": [],
                "_id": "5e6a2110ec00800028ede7a3",
                "module": "portal",
                "type": "fromOwner",
                "body": "test message",
                "id": "5e6a2110ec00800028ede7a3"
            },
            {
                "createdAt": "2020-03-12T11:46:24.231Z",
                "attachments": [],
                "_id": "5e6a2110ec00800028ede7a1",
                "module": "note",
                "type": "fromOwner",
                "body": "test_owner_from_listing_admin_k test_owner_from_listing_admin_m has reserved my private dungeon12 from Mar 19, 2020 at 03:00 PM\n\t\t\tuntil Mar 20, 2020 at 10:00 AM",
                "id": "5e6a2110ec00800028ede7a1"
            }
        ],
        "lastUpdatedFromGuest": "2020-03-12T11:46:24.231Z",
        "readLog": [],
        "lastModifiedAt": "2020-03-12T13:11:49.188Z",
        "subject": "test_owner_from_listing_admin_k test_owner_from_listing_admin_m has reserved my private dungeon12 from Mar 19, 2020 at 03:00 PM\n\t\t\tuntil Mar 20, 2020 ...",
        "lastUpdatedAt": "2020-03-12T13:11:49.186Z",
        "__v": 2,
        "id": "5e6a2110ec00800028ede7a0"
    }
}

Owners

The Owner object

{
    "ownersPortalSettings": {
        "bookedNights": true,
        "revenue": true
    },
    "listings": [
        "5e32fc021690ba0026f6f778"
    ],
    "locale": "en-US",
    "active": false,
    "allowReservations": false,
    "showReservationTooltips": true,
    "workingCapital": 0,
    "_id": "5e6b79c25f67330028bbbc20",
    "accountId": "596f6fe706112710005d96ff",
    "firstName": "test_test1",
    "lastName": "test_test1",
    "email": "test_test1@test.com",
    "address": "test address",
    "phone": "+380986410377",
    "picture": {
        "thumbnail": "https://cdn.filepicker.io/api/file/gQOIcCCnTs2PysfQDav6",
        "regular": "https://cdn.filepicker.io/api/file/gQOIcCCnTs2PysfQDav6"
    },
    "notes": "test notes",
    "createdAt": "2020-03-13T12:17:06.758Z",
    "fullName": "test_test1 test_test1",
    "__v": 0
}
Attribute Type Description
_id String Unique id
ownersPortalSettings OPSettings object
listings [String] ObjectId
locale String
active Boolean
allowReservations Boolean
showReservationTooltips Boolean
workingCapital Number
accountId String ObjectId
firstName String
lastName String
email String
address String
phone String
picture OPicture object
notes String
createdAt Date ISO
fullName String

The OPSettings object

Attribute Type Description
bookedNights Boolean
revenue Boolean

The OPicture object

Attribute Type Description
thumbnail String
regular String

Get list of owners

HTTP Request

GET /owners

Validators

Query Parameters

Parameter Default Format
limit Number Optional
pagination Boolean Optional
skip Number Optional

Example

Request

/owners?limit=15&pagination=true&skip=0

Response

{ results: [{Owner}, {Owner}, ...], count: 61, limit: 15, skip: 0 }

Create an owner

HTTP Request

POST /owners

Validators

Body

{
    "ownersPortalSettings": {
        "bookedNights": true,
        "revenue": true
    },
    "firstName": "test_test",
    "lastName": "test_test",
    "email": "test_test@test.com",
    "address": "test address",
    "phone": "+380986410377",
    "picture": {
        "thumbnail": "https://cdn.filepicker.io/api/file/gQOIcCCnTs2PysfQDav6",
        "regular": "https://cdn.filepicker.io/api/file/gQOIcCCnTs2PysfQDav6"
    },
    "notes": "test notes",
    "listings": [
        {
            "_id": "5e32fc021690ba0026f6f778",
            "picture": {
                "thumbnail": "https://cdn.filestackcontent.com/resize=height:200/mqfijPXwRnSqEwg3bohQ"
            },
            "pms": {
                "automation": {
                    "calendarSmartRules": {
                        "blockListings": []
                    }
                }
            },
            "tags": [
                "DL-792"
            ],
            "address": {
                "full": "Lva Tolstoho St, 29, L'viv, L'vivs'ka oblast, Ukraine, 79000"
            },
            "nickname": "test DL-792",
            "title": "test DL-792",
            "accountId": "596f6fe706112710005d96ff"
        }
    ],
    "active": false,
    "workingCapital": 0
}
Parameter Default Format
firstName Required
lastName Required
email Required
listings Required
ownersPortalSettings Optional
locale Optional
active Optional
allowReservations Optional
showReservationTooltips Optional
workingCapital Optional
accountId Optional
firstName Optional
lastName Optional
email Optional
address Optional
phone Optional
picture Optional
notes Optional
createdAt Optional
fullName Optional

Example

Body

{ "ownersPortalSettings": { "bookedNights": true, "revenue": true }, "firstName": "test_test", "lastName": "test_test", "email": "test_test@test.com", "address": "test address", "phone": "+380986410377", "picture": { "thumbnail": "https://cdn.filepicker.io/api/file/gQOIcCCnTs2PysfQDav6", "regular": "https://cdn.filepicker.io/api/file/gQOIcCCnTs2PysfQDav6" }, "notes": "test notes", "listings": [ { "_id": "5e32fc021690ba0026f6f778", "picture": { "thumbnail": "https://cdn.filestackcontent.com/resize=height:200/mqfijPXwRnSqEwg3bohQ" }, "pms": { "automation": { "calendarSmartRules": { "blockListings": [] } } }, "tags": [ "DL-792" ], "address": { "full": "Lva Tolstoho St, 29, L'viv, L'vivs'ka oblast, Ukraine, 79000" }, "nickname": "test DL-792", "title": "test DL-792", "accountId": "596f6fe706112710005d96ff" } ], "active": false, "workingCapital": 0 }

Response

{ "ownersPortalSettings": { "bookedNights": true, "revenue": true }, "listings": [ "5e32fc021690ba0026f6f778" ], "locale": "en-US", "active": false, "allowReservations": false, "showReservationTooltips": true, "workingCapital": 0, "_id": "5e6b79c25f67330028bbbc20", "accountId": "596f6fe706112710005d96ff", "firstName": "test_test", "lastName": "test_test", "email": "test_test@test.com", "address": "test address", "phone": "+380986410377", "picture": { "thumbnail": "https://cdn.filepicker.io/api/file/gQOIcCCnTs2PysfQDav6", "regular": "https://cdn.filepicker.io/api/file/gQOIcCCnTs2PysfQDav6" }, "notes": "test notes", "createdAt": "2020-03-13T12:17:06.758Z", "fullName": "test_test1 test_test1", "__v": 0 }

Retrieve an owner

HTTP Request

GET /owners/:id

Response

The Owner

{
    "ownersPortalSettings": {
        "bookedNights": true,
        "revenue": true
    },
    "listings": [
        "5e32fc021690ba0026f6f778"
    ],
    "locale": "en-US",
    "active": false,
    "allowReservations": false,
    "showReservationTooltips": true,
    "workingCapital": 0,
    "_id": "5e6b79c25f67330028bbbc20",
    "accountId": "596f6fe706112710005d96ff",
    "firstName": "test_test1",
    "lastName": "test_test1",
    "email": "test_test1@test.com",
    "address": "test address",
    "phone": "+380986410377",
    "picture": {
        "thumbnail": "https://cdn.filepicker.io/api/file/gQOIcCCnTs2PysfQDav6",
        "regular": "https://cdn.filepicker.io/api/file/gQOIcCCnTs2PysfQDav6"
    },
    "notes": "test notes",
    "createdAt": "2020-03-13T12:17:06.758Z",
    "fullName": "test_test1 test_test1",
    "__v": 0
}

Update an owner

HTTP Request

PUT /owners/:id

Validators

Body

Parameter Default Format
firstName Required
lastName Required
email Required
listings Required
ownersPortalSettings Optional
locale Optional
active Optional
allowReservations Optional
showReservationTooltips Optional
workingCapital Optional
accountId Optional
firstName Optional
lastName Optional
email Optional
address Optional
phone Optional
picture Optional
notes Optional
createdAt Optional
fullName Optional

Query Parameters

Parameter Default Format
accountId String Optional

Response

The Owner

Delete an owner

HTTP Request

DELETE /owners/:id

Validators

Response

Views

The view object

{
    "_id": "58936fc2e582af100036351a",
    "updatedAt": "2017-08-07T11:58:20.437Z",
    "section": "reservations",
    "fields": "checkIn checkOut confirmationCode listing guest",
    "sort": "checkIn",
    "title": "Upcoming Bookings (Copy)",
    "accountId": "563e0b6a08a2710e00057b82",
    "__v": 4,
    "shares": [
        {
            "contactId": "5926bdfb1bfe871000d0a745",
            "_id": "598855dc3c31bf0f0075858f"
        }
    ],
    "scheduledEmails": [
        {
            "recipient": "EMAIL@EMAIL.COM",
            "hour": 10,
            "_id": "589d11a2567d7d10000c41a3",
            "days": [
                0
            ]
        }
    ],
    "createdAt": "2017-02-02T17:43:30.207Z",
    "filters": [
        {
            "operator": "$gt",
            "field": "checkOut",
            "context": "now",
            "optionDisplayName": "is in the future",
            "_id": "556b2e43fe759c0e00e5cd15"
        },
        {
            "value": "confirmed",
            "operator": "$eq",
            "field": "status",
            "optionDisplayName": "is",
            "_id": "58936fc2e582af100036351c"
        },
        {
            "value": 4,
            "operator": "$eq",
            "field": "nightsCount",
            "optionDisplayName": "equals",
            "_id": "58936fc2e582af100036351b"
        }
    ]
}
Attribute Type Description
_id String Unique id
accountId String Id of the user owning this view
title String Title for the view
section String (Enum) reservations, listings, tasks, guest
filters [filters] (see below)
fields String Selection of fields, separated by space
sort String ascending sort , use - to descending sort
createdAt Date
updatedAt Date
scheduledEmails Array (scheduledEmail Object) (see below)
shares [shares] (see below)

The filters object

{
    "field": "checkIn",
    "operator": "$gt",
    "value": 0,
    "context": "now"
}
Parameter Default Description Example
field Required Subject of the filter
operator Required Enhanced MongoDB comparison operator: $eq, $not, $contains, $notcontains, $gt, $lt, $between
value Required Value to filter by.
context null Optional preprocessing. Options are now, createdAt, confirmedAt, canceledAt, alteredAt. When given, the date in value is relative to the context.

The scheduledEmails object

{
    "recipient": "EMAIL2@EMAIL.COM",
    "hour": 10,
    "_id": "598855c73c31bf0f007583d2",
    "days": [
        3,
        4,
        0
    ]
}
Parameter Default Description Example
days [Number] Array of numbers 0-6, number per day 4 (send on Thursday)
recipient String Emails separated by comma
hour Number when the report should be sent

The shares object

{
    "contactId": "5926bdfb1bfe871000d0a745",
    "_id": "598855dc3c31bf0f0075858f"
}
Parameter Default Description Example
contactId --- Required Contact ID to share with 5926bdfb1bfe871000d0a745

List all views

{
    "results": [
        {
            "_id": "597091be29050d10002ed4bc",
            "updatedAt": "2017-07-20T11:19:27.004Z",
            "section": "listings",
            "fields": "nickname title address.full tags picture.thumbnail active",
            "sort": "title",
            "title": "Active Listings (Copy)",
            "accountId": "563e0b6a08a2710e00057b82",
            "shares": [],
            "scheduledEmails": [],
            "createdAt": "2017-07-20T11:19:26.998Z",
            "filters": [
                {
                    "value": true,
                    "operator": "$eq",
                    "field": "active",
                    "_id": "597091bf29050d10002ed4be"
                },
                {
                    "value": true,
                    "operator": "$eq",
                    "field": "isListed",
                    "_id": "597091be29050d10002ed4bd"
                }
            ],
            "__v": 0
        }
    ],
    "count": 1,
    "fields": "",
    "limit": 25,
    "skip": 0
}

HTTP Request

GET /views

Query Parameters

Parameter Default Description Example
section Required One of guest,reservations,tasks,listings listings
fields null Selection of fields, separated by space. When null retrieves all object. "title"
limit 25 Pagination 25
skip 0 Pagination 0

Response

Views objects

Create a view

Response

{
    "__v": 0,
    "updatedAt": "2017-09-13T14:48:58.362Z",
    "title": "exampleView",
    "section": "reservation",
    "accountId": "563e0b6a08a2710e00057b82",
    "_id": "59b9455aff91be100056eccf",
    "shares": [],
    "scheduledEmails": [],
    "createdAt": "2017-09-13T14:48:58.360Z",
    "filters": []
}

HTTP Request

POST /views

Body

Parameter Default
title Required
section Required

Example

Body

{"title": "exampleView", "section":"reservation"}

Response

The inserted object.

Retrieve a view

{
    "_id": "58936fc2e582af100033251a",
    "updatedAt": "2017-03-01T05:08:22.018Z",
    "section": "reservations",
    "fields": "checkIn checkOut confirmationCode listing guest",
    "sort": "checkIn",
    "title": "example",
    "accountId": "563e0b6a08a2710e00057b82",
    "__v": 1,
    "shares": [],
    "scheduledEmails": [],
    "createdAt": "2017-04-05T17:23:31.277Z",
    "filters": [
        {
            "operator": "$gt",
            "field": "checkOut",
            "context": "now",
            "optionDisplayName": "is in the future",
            "_id": "556b2e43fe759c0e00e5cd32"
        }
    ]
}

HTTP Request

GET /views/:id

Report tokens

Can only retrieve objects owned by connected token. 403 otherwise.

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space "title"

Response

View object

Update a view

HTTP Request

PUT /views/:id

Response

Retrieve the updated view, selection of updated fields.

Delete a view

HTTP Request

DELETE /views/:id

Response

OK

Guests

The guest object

{
    "_id" : "5803ca18e48f450300c76173",
    "fullName" : "Kristen",
    "firstName" : "Kristen",
    "accountId" : "563e0b6a08a2710e00057b82",
    "hasVerifiedId" : false,
    "hometown" : "US",
    "languages" : "",
    "paymentMethods" : [],
    "communicationMethods" : [
        "airbnb"
    ],
    "airbnb" : {
        "id" : 32931005,
        "url" : "https://www.airbnb.com/users/show/32931005",
        "firstName" : "Kristen",
        "lastName" : null,
        "fullName" : "Kristen"
    },
    "phones" : [],
    "emails" : [],
    "pictures" : [
        {
            "thumbnail" : "//guestybookings.s3.amazonaws.com/guests/thumbnail_e2cb8a96-45a9-45cd-b28e-57e1ca1fc988.jpg",
            "large" : "//guestybookings.s3.amazonaws.com/guests/large_e2cb8a96-45a9-45cd-b28e-57e1ca1fc988.jpg",
            "regular" : "//guestybookings.s3.amazonaws.com/guests/regular_e2cb8a96-45a9-45cd-b28e-57e1ca1fc988.jpg",
            "_id" : "5803ca18e48f450300c76174"
        }
    ],
    "verifications" : [
        "Email address"
    ],
    "__v" : 0
}
Attribute Type Description
_id String Unique id
accountId ObjectId (String) Id of owning user
firstName String
lastName String
fullName String
company String
hometown String
address Object (see below)
hasVerifiedId Boolean
verifications [String] List of verifications
picture Object (see below)
pictures [picture] List of pictures
email String Main use email address
emails [String] List of emails
privateEmail String
phone String Main use phone number
phones [String] List of phones
hasPossiblyBadReviews Boolean
confirmed Boolean True if the guest has confirmed bookings
languages [String] List of languages the guest knows
airbnb Object standard (see below)
airbnb2 Object upgraded (see below)
rentalsUnited Object (see below)
bookingCom Object (see below)
homeAway Object (see below)
tripAdvisor Object (see below)
notes String
communicationMethods [Enum] airbnb, email, sms, airbnb2, tripAdvisor
paymentMethods [ObjectId] array of paymentMethod Ids
paymentProviders Object
---stripe Object
------customerId String
policy Object (see below)

The address object

{
"address" : {
        "street" : "2609  Haul Road",
        "city" : "Saint Paul",
        "country" : "US",
        "countryCode" : "001",
        "zipCode" : "55102"
    }
}
Parameter Type Description
street String
city String
country String
countryCode String
zipCode String

The picture object

{
"pictures" : [
        {
            "thumbnail" : "//guestybookings.s3.amazonaws.com/guests/thumbnail_e2cb8a96-45a9-45cd-b28e-57e1ca1fc988.jpg",
            "large" : "//guestybookings.s3.amazonaws.com/guests/large_e2cb8a96-45a9-45cd-b28e-57e1ca1fc988.jpg",
            "regular" : "//guestybookings.s3.amazonaws.com/guests/regular_e2cb8a96-45a9-45cd-b28e-57e1ca1fc988.jpg",
            "_id" : "5803ca18e48f450300c76174"
        }
    ]
}
Parameter Type Description
thumbnail String
large String
regular String

The airbnb object

{
"airbnb" : {
        "id" : 32931005,
        "url" : "https://www.airbnb.com/users/show/32931005",
        "firstName" : "Kristen",
        "lastName" : null,
        "fullName" : "Kristen"
    }
}
Parameter Type Description
id Number
url String
firstName String
lastName String
fullName String

The airbnb2 object

{
"airbnb2" : {
        "id" : 32931005,
        "index" : "1111111111111",
        "url" : "https://www.airbnb.com/users/show/32931005",
        "firstName" : "Kristen",
        "lastName" : null,
        "fullName" : "Kristen"
    }
}
Parameter Type Description
id Number
index String Unique index
url String
firstName String
lastName String
fullName String

The rentalsUnited object

{
"rentalsUnited": {
        "fullName": "Sergey Grinblat",
        "firstName": "Sergey",
        "lastName": "Grinblat"
    }
}
Parameter Type Description
firstName String
lastName String
fullName String

The bookingCom object

{
"bookingCom": {
        "fullName": "Sergey Grinblat",
        "firstName": "Sergey",
        "lastName": "Grinblat"
    }
}
Parameter Type Description
firstName String
lastName String
fullName String

The homeAway object

{
"homeAway": {
        "title": "Prof", 
        "fullName": "Sergey Grinblat",
        "firstName": "Sergey",
        "lastName": "Grinblat"
    }
}
Parameter Type Description
title String
firstName String
lastName String
fullName String

The tripAdvisor object

{
"tripAdvisor": {
        "title": "Prof", 
        "fullName": "Sergey Grinblat",
        "firstName": "Sergey",
        "lastName": "Grinblat"
    }
}
Parameter Type Description
title String
firstName String
lastName String
fullName String

The policy object

{
    "policy": {
            "privacy": {
                "dateOfAcceptance": "2020-01-21T06:21:12.526Z",
                "isAccepted": true,
                "version": 1,
            },
            "marketing": {
                "dateOfAcceptance": "2020-01-21T06:21:12.526Z",
                "isAccepted": true,
            }
        }
}
Parameter Type Description
privacy Object
--- dateOfAcceptance Date
-----isAccepted Boolean
----version Number

--- market

List all guests

    {
        "count": 1,
        "limit": 25,
        "skip": 0,
        "results": [
            {
                "_id" : "58243555fb61770400aede31",
                "fullName" : "Koby Soto",
                "lastName" : "Soto",
                "firstName" : "Koby",
                "accountId" : "55b9f9b53935550e004b6c5d",
                "hasVerifiedId" : true,
                "hometown" : "US",
                "languages" : "",
                "paymentMethods" : [],
                "communicationMethods" : [
                    "airbnb"
                ],
                "airbnb" : {
                    "id" : 8555466,
                    "url" : "https://www.airbnb.com/users/show/8555466",
                    "firstName" : "Koby",
                    "lastName" : "Soto",
                    "fullName" : "Koby Soto"
                },
                "phones" : [],
                "emails" : [],
                "pictures" : [],
                "verifications" : [
                    "Email address",
                    "Phone number",
                    "Personal info"
                ]
            }
        ]
    }

HTTP Request

GET /guests

Query Parameters

Parameter Default Description Example
q null Search query string. Searches in fullname, company, hometown, emails, phones "Koby"
include_confirmed true Boolean true
include_unconfirmed false Boolean false
fields null Selection of fields, separated by space. When null retrieves all object. "firstName lastName phone"
limit 25 Pagination, max: 100 25
sort fullName ascending alphabetical sort , use - to descending alphabetical sort fullName/-fullName
skip 0 Pagination 0

Response

Array of requested guests

Create a guest

Response

{
    "__v": 0,
    "accountId": "563e0b6a08a2710e00057b82",
    "_id": "59b9466532123a1000b8665e",
    "paymentMethodIds": [],
    "communicationMethods": [],
    "airbnb": {
        "id": 1505314405905
    },
    "phones": [],
    "emails": [],
    "pictures": [],
    "verifications": []
}

HTTP Request

POST /guests

Body

No required fields.

Example

Body

Body is empty.

Response

The inserted object.

Retrieve a guest

HTTP Request

GET /guests/:id

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space. When null retrieve the main properties of the object. We recommend always specifying the specific fields you'd like to receive to ensure that you get them. Please see the full list above. "firstName lastName"

Response

Guest object

Update a guest

HTTP Request

PUT /guests/:id

Response

The updated guest object.

Delete a guest

HTTP Request

DELETE /guests/:id

Response

OK

Create payment method

Response

{
  "saveForFutureUse": true,
  "status": "ACTIVE",
  "type": "PHYSICAL",
  "_id": "paymentMethodId",
  "accountId": "accountId",
  "method": "STRIPE",
  "payload": {
    "id": "pm_...",
    "object": "payment_method",
    "billing_details": {
      "address": {
        "city": null,
        "country": null,
        "line1": null,
        "line2": null,
        "postal_code": null,
        "state": null
      },
      "email": null,
      "name": "test test",
      "phone": null
    },
    "card": {
      "brand": "visa",
      "checks": {
        "address_line1_check": null,
        "address_postal_code_check": null,
        "cvc_check": "pass"
      },
      "country": "US",
      "exp_month": 4,
      "exp_year": 2024,
      "fingerprint": "6i2ad2EHQpQJ8PeH",
      "funding": "credit",
      "generated_from": null,
      "last4": "4242",
      "three_d_secure_usage": {
        "supported": true
      },
      "wallet": null
    },
    "created": 1589969558,
    "customer": "cus_HJRos0NhFFIdqd",
    "livemode": false,
    "type": "card"
  },
  "createdAt": "2020-05-20T10:12:39.438Z",
  "last4": "4242",
  "brand": "visa",
  "__v": 0
}

HTTP Request

POST /guests/:id/payment-methods

Body

Parameter Default Description
stripeCardToken Required id from stripe payment method
skipSetupIntent false should be true if credit card was collected with setup_intent performed on the frontend https://stripe.com/docs/js/setup_intents/confirm_card_setup

example

{ "stripeCardToken": "pm_...", "skipSetupIntent": false }

Side-effect

If there's auto-payments with payment method CASH (no payment method defined in the UI), then they will be changed to the added payment method automatically

Retrieve payment methods

Response

[
    {
        "saveForFutureUse": true,
        "status": "ACTIVE",
        "type": "PHYSICAL",
        "_id": "paymentMethodId",
        "accountId": "accountId",
        "method": "STRIPE",
        "payload": {
            "id": "pm_...",
            "object": "payment_method",
            "customer": "cus_...",
            "name": "test test",
            "address_city": null,
            "address_country": null,
            "address_line1": null,
            "address_line2": null,
            "address_state": null,
            "address_zip": null,
            "address_line1_check": null,
            "address_zip_check": null,
            "cvc_check": "pass",
            "brand": "visa",
            "country": "US",
            "exp_month": 4,
            "exp_year": 2024,
            "fingerprint": "6i2ad2EHQpQJ8PeH",
            "funding": "credit",
            "last4": "4242"
        },
        "createdAt": "2020-05-20T10:12:39.438Z",
        "last4": "4242",
        "brand": "visa",
        "__v": 0
    }
]

HTTP Request

GET /guests/:id/payment-methods

Response

Payment methods list

Phone Book Contacts

The contact object

{
    "_id": "57e9437fd0b2c00f00d3d808",
    "phone": "972541723456",
    "fullName": "(GodOfWar) Sergey Grinblat",
    "preferredContactMethod": "email",
    "firstName": "Sergey",
    "lastName": "Grinblat",
    "company": "Guesty",
    "notes": "Examples notes",
    "title": "GodOfWar",
    "email": "example@guesty.com",
    "accountId": "563e0b6a08a2710e00057b82",
    "phones": [
        "972541723456"
    ],
    "emails": [
        "example@guesty.com"
    ],
    "__v": 1
}
Attribute Type Description
_id String Unique id
accountId ObjectId (String) Owner
firstName String
lastName String
fullName String
nickname String
title String
company String
picture Picture (Object) (see below)
emails Array (String)
phones Array (String)
preferredContactMethod String
email String Default email to use
phone String Default phone to use
notes String

List all contacts

{
    "results": [
        {
            "_id": "57e9437fd0b2c00f00d3d808",
            "phone": "97254172342",
            "fullName": "Sergey Grinblat",
            "preferredContactMethod": "email",
            "firstName": "Sergey",
            "lastName": "Grinblat",
            "email": "example@guesty.com",
            "accountId": "563e0b6a08a2710e00057b82",
            "phones": [
                "97254172342"
            ],
            "emails": [
                "example@guesty.com"
            ],
            "__v": 0
        }
    ],
    "count": 1,
    "fields": "",
    "limit": 50,
    "skip": 0
}

HTTP Request

GET /contacts

Query Parameters

Parameter Default Description Example
accountId --- Optional with admin token, Unavailable with user token. 531968414930a7f09b075800
fields null Selection of fields, separated by space "fullName"
ids null List of String (ObjectId) to get [53196898493567f023034845]
q null Search text to filter by name, emails, phones Jack
sort null Sorting "nickname"
limit 50 Pagination, max: 100 50
skip 0 Pagination 0

Response

The requested Contacts objects

Create a contact

Response

{
    "accountId": "596f6fe706112710005d96ff",
    "company": "Hogwarts",
    "email": "thehalfbloodprince@hogwarts.com",
    "emails": ["thehalfbloodprince@hogwarts.com"],
    "firstName": "Severus",
    "fullName": "(Magician) Severus Snape",
    "lastName": "Snape",
    "phones": [],
    "preferredContactMethod": "email",
    "title": "Magician",
    "__v": 0,
    "_id": "5e16f0905cc00c0021939a9d"
}

HTTP Request

POST /contacts

Body

No required fields.

Example

Body

{ "company": "Hogwarts", "email": "thehalfbloodprince@hogwarts.com", "emails": ["thehalfbloodprince@hogwarts.com"], "firstName": "Severus", "lastName": "Snape", "phones": [], "preferredContactMethod": "email", "title": "Magician" }

Response

The created object.

Retrieve a contact

{
    "_id": "57e9437fd0b2c00f00d3d808",
    "phone": "97254172342",
    "fullName": "Sergey Grinblat",
    "preferredContactMethod": "email",
    "firstName": "Sergey",
    "lastName": "Grinblat",
    "email": "example@guesty.com",
    "accountId": "563e0b6a08a2710e00057b82",
    "phones": [
        "97254172342"
    ],
    "emails": [
        "example@guesty.com"
    ],
    "__v": 0
}

HTTP Request

GET /contacts/:id

Authorization

Only accessible to Admin or User tokens.

User tokens

Can only retrieve objects owned by connected user. 403 otherwise.

Required permission: phoneBook.view. Can only return items of included listings.

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space. When null retrieve the main properties of the object. We recommend always specifying the specific fields you'd like to receive to ensure that you get them. Please see the full list above. "firstName lastName"

Response

Contact object.

Update a contact

HTTP Request

PUT /contacts/:id

Authorization

Only accessible to Admin or User tokens.

Admin tokens

Available fields: All object, except accountId (which is ignored).

User tokens

Can only update objects owned by connected user. 403 otherwise. Available fields: All object, except accountId (which is ignored).

Required permission: phoneBook.edit. Can only edit items of included listings.

Response

The updated object with only the fields that were sent in body.

Delete a contact

HTTP Request

DELETE /contacts/:id

Authorization

Only accessible to Admin or User tokens.

User tokens

Can only delete objects owned by connected user. 403 otherwise.

Required permission: phoneBook.edit. Can only delete items of included listings.

Response

OK

Auto Tasks

The auto task object

{
    "_id": "5899e50cdef6f910004f1561",
    "templateId": "5899e4e0d944981000d6ecc8",
    "event": "reservation confirmed",
    "canStartAfter": "current confirmed",
    "mustFinishBefore": "current confirmed minus 2 hours",
    "startTime": "current checkIn",
    "accountId": "563e0b6a08a2710e00057b82",
    "__v": 0
}
Attribute Type Description
_id String Unique id
accountId ObjectId (String) Owner
templateId ObjectId (String) Task template Id
event String reservation confirmed, rental period defined, calendar updated
startTime String formula for exact start time
canStartAfter String formula for flexible start time
mustFinishBefore String formula for flexible end time

List all auto tasks

{
    "count": 1,
    "limit": 25,
    "skip": 0,
    "results": [
        {
            "_id": "587e42851f33d31000f39c1d",
            "templateId": "587e42721f33d31000f39c11",
            "event": "rental period defined",
            "canStartAfter": "",
            "mustFinishBefore": "",
            "startTime": "start at 09:00",
            "accountId": "563e0b6a08a2710e00057b82",
            "__v": 0
        }
    ]
}

HTTP Request

GET /auto-tasks

Query Parameters

Parameter Default Description Example
accountId --- Optional with admin token, Unavailable with user token. 531968414930a7f09b075800
fields null Selection of fields, separated by space templateId event
limit 25 Pagination 25
skip 0 Pagination 0

Response

createdBy is populated as a user object with the fields: _id, fullName, picture.thumbnail. assignee is a populated version of assigneeId as a user object with the fields: _id, fullName, picture.thumbnail.

Create an auto task

Response

{
    "__v": 0,
    "templateId": "59b9492e32123a1000b86af3",
    "event": "reservation confirmed",
    "startTime": "current checkOut minus 4 hours",
    "accountId": "563e0b6a08a2710e00057b82",
    "_id": "59b9498bff91be100056fa3a"
}

HTTP Request

POST /auto-tasks

Body

Parameter Default
templateId Required
event Required
statTime Required

Examples

Body

{"templateId":"59b9492e32123a1000b86af3","event":"reservation confirmed","startTime":"current checkOut minus 4 hours"}

Response

The created object.

Retrieve a task

HTTP Request

GET /auto-tasks/:id

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space. When null retrieve the main properties of the object. We recommend always specifying the specific fields you'd like to receive to ensure that you get them. Please see the full list above. event

Response

Default task object.

Update an auto task

HTTP Request

PUT /auto-tasks/:id

Response

The updated object with only the fields that were sent in body.

Delete an auto task

HTTP Request

DELETE /auto-tasks/:id

Response

OK

Tasks

The task object

Attribute Type Description
_id String Unique id
accountId ObjectId (String) Owner
title String the task itself
description String task description
priority Enum (Number) 1-5
assigneeGroup [String] tags
assigneeId ObjectId (String) ref to User
assigneeFullName String User full name
supervisorId ObjectId (String) ref to User
price Number task tariff
checklist Array (String)
attachments [attachment object] (see below)
afterEffects [afterEffect object] (see below)
tags [String] List of tags the task is under
status Enum pending, confirmed, in progress, completed, canceled
createdAt Date Date created
createdBy ObjectId (String) ref to User
startTime Date
endTime Date
plannedDuration Number planned duration for the task (in hours)
actualDuration Number actual duration for the task (in hours)
canStartAfter String formula for flexible start time
mustFinishBefore String formula for flexible end time
confirmedAt Date
startedAt Date
completedAt Date
completedBy User (Object) Fields: _id, fullName, picture.thumbnail
listingId ObjectId (String) ref to Listing
reservationId ObjectId (String) ref to Reservation
comments [comment object] (see below)
lastComment String
checklistFinished [String]
prototypeId ObjectId (String) link to auto task
feedbackScore Number [0-5]
feedbackNotes String
editedFields [String] fields that were manually edited and should not be automatically overridden
dateForSort Date
enumeratedStatus Number
log [log object] (see below)

The log object

{
"log": [
                {
                    "event": "Task was updated",
                    "by": "Roei Timor",
                    "_id": "58163205f4ff4b0f005f1070",
                    "changes": [
                        {
                            "field": "editedFields 0",
                            "_id": "58163205f4ff4b0f005f1073",
                            "diff": [
                                {
                                    "value": "priority",
                                    "added": true,
                                    "_id": "58163205f4ff4b0f005f1074"
                                }
                            ]
                        },
                        {
                            "field": "priority",
                            "_id": "58163205f4ff4b0f005f1071",
                            "diff": [
                                {
                                    "value": "1",
                                    "added": true,
                                    "_id": "58163205f4ff4b0f005f1072"
                                }
                            ]
                        }
                    ],
                    "at": "2016-10-30T17:46:45.627Z"
                }
     ]
}
Attribute Type Description
event String Required
description String
by String
at Date
changes [change object] (see below)

The change object

Attribute Type Description
field String
diff [diff object] (see below)

The diff object

Attribute Type Description
value String
added Boolean
removed Boolean

The comment object

Attribute Type Description
text String
by ObjectId (String) ref to User
at Date

The afterEffect object

{
    "afterEffects": [
        {
            "action": "CHANGE_CLEANING_STATUS",
            "_id": "58db6d2255652510008f0f0e",
            "payload": {
                "message": {
                    "attachments": []
                }
            }
        },
        {
            "action": "SEND_EMAIL",
            "_id": "58db6d2255652510008f0f0d",
            "payload": {
                "target": "USER",
                "targetId": "57d189e89528720f00e5c2fa",
                "message": {
                    "body": "<p>HIIIIIIII</p>\n",
                    "subject": "HI",
                    "attachments": []
                }
            }
        }
    ]
}
Attribute Type Description
action Enum CHANGE_CLEANING_STATUS, SEND_SMS, SEND_EMAIL
payload (payload object) (see below)

The payload object

Attribute Type Description
target Enum user, contact, guest, supervisor
targetId ObjectId ref to User
message Object the message object

The message object

Attribute Type Description
subject String
body String
attachment Object (see below)

The attachment object

Attribute Type Description
_id String Unique id
url String Required, attachment file url
title String
mimetype String
size Number
client String

comments

Array of comments:

{
    "comments": [
                    {
                        "text": "Fff",
                        "by": "57d189e89528720f00e5c2fa",
                        "_id": "57fa45fbe966d50f00fa088a",
                        "at": "2016-10-09T13:28:27.034Z"
                    },
                    {
                        "text": "Check",
                        "by": "57d189e89528720f00e5c2fa",
                        "_id": "581a0f8e3bb4af0f00beb1c2",
                        "at": "2016-11-02T16:08:46.655Z"
                    }
                ]
}
Attribute Type Description
_id String Unique id
text String Required, the comment
by User (Object) Fields: _id, fullName, picture.thumbnail
at Date Timestamp

List all tasks

{
    "results": [
        {
            "_id": "582b3933b6e8cc1000fb2cc1",
            "endTime": "2016-12-08T14:00:00.000Z",
            "actualDuration": "2",
            "startedAt": null,
            "completedAt": "2016-12-04T16:34:38.332Z",
            "confirmedAt": null,
            "plannedDuration": 3,
            "title": "Task for video",
            "description": "Clean the beach house.\nMake sure to clean the window in the living room.",
            "supervisorId": "56f93baaa2a34bec3605f416",
            "assigneeId": "56f93baaa2a34bec3605f416",
            "canStartAfter": "2016-12-08T08:00:00.000Z",
            "mustFinishBefore": null,
            "startTime": "2016-12-08T11:00:00.000Z",
            "accountId": "563e0b6a08a2710e00057b82",
            "prototypeId": "582b3933b6e8cc1000fb2ca3",
            "reservationId": "58170e8cb12fd30f00884412",
            "listingId": "57e2476e58621d0f003eaac5",
            "priority": 1,
            "log": [
                {
                    "event": "Task was created",
                    "by": "system",
                    "_id": "582b3933b6e8cc1000fb2cc2",
                    "changes": [],
                    "at": "2016-11-15T16:34:59.405Z"
                },
                {
                    "event": "Task was updated",
                    "by": "Roei Timor",
                    "_id": "582b3c572056f610002343ee",
                    "changes": [
                         {
                            "field": "status",
                            "_id": "582b3c572056f610002343ef",
                            "diff": [
                                {
                                    "removed": true,
                                    "value": "pending",
                                    "_id": "582b3c572056f610002343f1"
                                },
                                {
                                    "added": true,
                                    "value": "completed",
                                    "_id": "582b3c572056f610002343f0"
                                }
                            ]
                        }
                    ],
                    "at": "2016-11-15T16:48:23.400Z"
                }
            ],
            "editedFields": [
                "status"
            ],
            "checklistFinished": [],
            "comments": [],
            "status": "completed",
            "afterEffects": [
                {
                    "action": "CHANGE_CLEANING_STATUS",
                    "_id": "58db6d2255652510008f0f0e",
                    "payload": {
                        "message": {
                            "attachments": []
                        }
                    }
                }
            ],
            "attachments": [],
            "checklist": [
                "TV",
                "Wi-Fi router",
                "Hair Dryer"
            ],
            "assigneeGroup": [],
            "createdAt": "2016-11-15T17:46:43.288Z",
            "__v": 3,
            "dateForSort": "2017-11-02T09:00:00.000Z",
            "enumeratedStatus": 1,
            "completedBy": "57d189e89528720f00e5c2fa",
            "tags": [],
            "assigneeFullName": "John Smith",
            "nextReservation": {
                "_id": "5884e79cded55810009bb2dc"
            },
            "prevReservation": null,
            "nextReservationId": "5884e79cded55810009bb2dc"
        }
    ],
    "title": "Tasks Report",
    "count": 1,
    "fields": "",
    "limit": 25,
    "skip": 0
}

HTTP Request

GET /tasks

Query Parameters

Parameter Default Description Example
listingId null Filter by specific listing "531968414930a7f09b075800"
reservationId null Filter by specific reservation "531968414930a7f09b075800"
done false Whether to show completed tasks or uncompleted tasks or both.
assignee null Filter by assignee's user id "531968414930a7f09b075800"
viewId null Pull a specific view (view is a saved settings of accountId, filters, fields, sort) 556d95083c59ae58e3fdd8f4
fields null Selection of fields, separated by space "title"
sort createdAt; completedAt in completed mode Sorting "title"
limit 25 Pagination, max: 100 25
skip 0 Pagination 0

Response

createdBy is populated as a user object with the fields: _id, fullName, picture.thumbnail.

completedBy is populated as a user object with the fields: _id, fullName, picture.thumbnail.

assignee is a populated version of assigneeId as a user object with the fields: _id, fullName, picture.thumbnail.

listing is a populated version of listingId as a listing object with the fields: _id, title, nickname, picture.thumbnail.

reservation is a populated version of reservationId as a reservation object with the fields: _id, confirmationCode.

Create a task

Response

{
    "__v": 0,
    "title": "Mana Mana",
    "accountId": "563e0b6a08a2710e00057b82",
    "_id": "59b94b67ff91be1000570008",
    "log": [],
    "editedFields": [],
    "checklistFinished": [],
    "comments": [],
    "createdAt": "2017-09-13T15:14:47.205Z",
    "status": "pending",
    "tags": [],
    "afterEffects": [],
    "attachments": [],
    "checklist": [],
    "assigneeGroup": [],
    "assigneeId": "5cb6d5108b308f0020847b61",
    "supervisorId": "5cb6d5108b308f0020847b61",
    "checklist": [
        "clean api docs"
    ],
    "plannedDuration": 2,
    "description": "stam task",
    "startTime": "2020-01-29T10:00:00.000Z",
    "canStartAfter": "2020-01-26T10:00:00.000Z",
    "mustFinishBefore": "2020-01-31T10:00:00.000Z",
    "priority": 1,
    "listingId": "55b9faceb6400f0e00b59d60",
    "reservationId": "5e0df09b354975001f86f839",
    "createdBy": "5d63eb24814cb900201b6786",
    "confirmedAt": null,
    "completedAt": null,
    "completedBy": null,
    "startedAt": null,
    "actualDuration": null,
    "endTime": "2020-01-29T12:00:00.000Z",
    "enumeratedStatus": 6,
    "dateForSort": "2020-01-29T10:00:00.000Z",
    "assigneeFullName": "john doe"
}

HTTP Request

POST /tasks

Body

Parameter Default Description Example
title Required Title "My Task"
plannedDuration --- Planned duration (hours) 2
description --- Description "Cleaning Task"
startTime --- Actual start time "2020-01-29T10:00:00.000Z"
canStartAfter --- Can start after "2020-01-29T10:00:00.000Z"
mustFinishBefore --- Must finish before "2020-01-29T10:00:00.000Z"
priority --- Priority 1
listingId --- Listing id "55b9faceb6400f0e00b59d60"
reservationId --- Reservation id "5e0df09b354975001f86f839"
checklist --- Checklist array ["Clean", "Order"]
supervisorId --- Supervisor id "5cb6d5108b308f0020847b61"
assigneeId --- Assignee id "5cb6d5108b308f0020847b61"

Example

Body

{"title":"Mana Mana"}

Response

The created object.

Retrieve a task

HTTP Request

GET /tasks/:id

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space. When null retrieve the main properties of the object. We recommend always specifying the specific fields you'd like to receive to ensure that you get them. Please see the full list above. "title"

Response

The requested Task object.

Update a task

HTTP Request

PUT /tasks/:id

Response

The updated object with only the fields that were sent in body.

Delete a task

HTTP Request

DELETE /tasks/:id

Response

OK

Export as CSV

HTTP Request

GET /tasks.csv

Same as /tasks but results are returned as a downloadable csv file

Send results in email

HTTP Request

POST /tasks.email

Same as /tasks but results are sent as an email

Body Parameters

Parameter Default Description Example
to Required Address of recipient koby@guesty.com

Saved replies

The saved reply object

Attribute Type Description
_id ObjectId Unique id
accountId ObjectId Owner user
listingIds [ObjectId] Related listings
excludeListingIds [ObjectId] Related listings
filters [filters] Filters Object
tags [String]
folder String Group replies in a folder
question String
answer String
applyWhenNoBooking Boolean
applyWhenHasBooking Boolean
isAbstract Boolean
type String (Enum) host, guest, contact, review
reviewType String public, private
language String 2 letters ISO code

The filters Object

Attribute Type Description
field String Subject of the filter - listing.tags or listing.address.city
operator String Enhanced MongoDB comparison operator: $eq, $not, $contains, $notcontains, $gt, $lt, $between
value String-Number Value to filter by.

List all saved replies

{
    "count": 1,
    "limit": 25,
    "skip": 0,
    "results": [
        {
            "_id": "563e0c2808a2710e00057b92",
            "language": "en",
            "isAbstract": false,
            "applyWhenNoBooking": true,
            "applyWhenHasBooking": true,
            "listingsIds": null,
            "__v": 0,
            "type": "guest",
            "question": "Check in time",
            "answer": "Check in is at {{checkin_time}}.",
            "accountId": "563e0b6a08a2710e00057b82"
        }
    ]
}

HTTP Request

GET /saved-replies

Query Parameters

Parameter Type Default Description Example
accountId String null Limit to a specific account 531968414930a7f68b0724504
listingId String null Limit to a specific listing 531968414930a7f09b075800
returnDefault Boolean null To get Guesty defaults SRs true
q String null Search query string. Searches in question, folder
fields String null Selection of fields, separated by space createdAt
sort String null Field to sort by. Prepend - for DESC. createdAt
limit Number 25 Pagination 25
skip Number 0 Pagination 0

Response

Array of saved replies objects

Create a saved reply

{
    "__v": 0,
    "question": "Mirror, mirror, on the wall, Who in this land is fairest of all?",
    "answer": "not you?",
    "accountId": "563e0b6a08a2710e00057b82",
    "_id": "59b92e3832123a1000b68a94",
    "language": "en",
    "type": "guest",
    "isAbstract": false,
    "applyWhenNoBooking": true,
    "applyWhenHasBooking": true
}

HTTP Request

POST /saved-replies

Body

Parameter Type Default Description Example
question String Required Question Mirror, mirror, on the wall, Who in this land is fairest of all?
answer String Required Answer not you?
applyWhenHasBooking Boolean true true
applyWhenNoBooking Boolean true true
type String guest [user, guest, contact, review] guest
listingIds Array of String (ObjectId) Apply saved-replied for specific listings [59b92e3832123a1000b68a94]
excludeListingIds Array of String (ObjectId) Exclude saved-replied for specific listings [59b92e3832123a1000b68a94]
filters Array of filters Apply saved-replied to listings which match the filters

The filters Object

Attribute Type Description
field String Required Subject of the filter - listing.tags or listing.address.city
operator Required Enhanced MongoDB comparison operator: $eq, $not, $contains, $notcontains, $gt, $lt, $between
value Required Value to filter by.

Example

Body

{"question":"Mirror, mirror, on the wall, Who in this land is fairest of all?", "answer": "not you?"}

Response

The inserted object.

Retrieve a saved reply

{
    "_id": "563e0c2808a2710e00057b92",
    "__v": 0,
    "question": "Check in time",
    "answer": "Check in is at {{checkin_time}}.",
    "accountId": "563e0b6a08a2710e00057b82",
    "language": "en",
    "type": "guest",
    "isAbstract": false,
    "applyWhenNoBooking": true,
    "applyWhenHasBooking": true,
    "tags": [],
    "listingsIds": null
}

HTTP Request

GET /saved-replies/:id

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space ``

Response

The requested object.

Update a saved reply

HTTP Request

PUT /saved-replies/:id

Body

All saved reply fields apart from accountId are editable

Response

The updated object.

Delete a saved reply

HTTP Request

DELETE /saved-replies/:id

Response

OK

List all saved replies by ListingId

{
    "count": 1,
    "limit": 25,
    "skip": 0,
    "results": [
        {
            "_id": "563e0c2808a2710e00057b92",
            "language": "en",
            "isAbstract": false,
            "applyWhenNoBooking": true,
            "applyWhenHasBooking": true,
            "listingsIds": null,
            "__v": 0,
            "type": "guest",
            "question": "Check in time",
            "answer": "Check in is at {{checkin_time}}.",
            "accountId": "563e0b6a08a2710e00057b82"
        }
    ]
}

HTTP Request

GET /saved-replies/listing/:id

Query Parameters

Parameter Type Default Description Example
listingId String null Limit to a specific listing 531968414930a7f09b075800
q String null Search query string. Searches in question, folder
fields String null Selection of fields, separated by space createdAt
sort String question Field to sort by. Prepend - for DESC. createdAt
limit Number 20 Pagination 20
skip Number 0 Pagination 0

Response

Array of saved replies objects by listing

Hooks

The hook object

Attribute Type Description
_id String (ObjectId) Unique id
accountId String (ObjectId)
listingIds [String (ObjectId)] Related listings
excludeListingIds [String (ObjectId)] Excluded listings
enabled Boolean Default: true
name String Hook's name
filters Array of filters See filters object
action String (Enum) send email, send sms, send platform message, receptionists dashboard, internal notes
target String (Enum) user, guest, contact
when String The delay from the trigger event
replyTo String For email hooks - set a replyTo that differs from the sender
trigger String(Enum) reservation confirmed, reservation altered, reservation canceled, check in, check out
humanRepresentation String Textual representation
templateId String (ObjectId) Unique id
atTime String Specific hour to run this hook. Format HH:mm (24 hours)

The filters Object

Attribute Type Description
field String Required Subject of the filter
operator Required Enhanced MongoDB comparison operator: $eq, $not, $contains, $notcontains, $gt, $lt, $between
value Required Value to filter by.

The to object

Attribute Type Description
userId String (ObjectId) User when target is "user"
contactId String (ObjectId) Contact when target is "contact"

The email object

Attribute Type Description
subject String Subject line for the email
body String Body in html format
attachments
cc Array (String) Array of emails to send this email in cc
bcc Array (String) Array of emails to send this email in bcc

The sms object

Attribute Type Description
body String Text of message, plain format

The platform object

Attribute Type Description
body String Text of message, plain format

The task object

Attribute Type Description
body String Text of task, plain format
priority String (Enum) high, medium, low

List all hooks

{
    "count": 1,
    "limit": 25,
    "skip": 0,
    "results": [
        {
            "_id": "595cf0fe6e327d1000cac401",
            "accountId": "563e0b6a08a2710e00057b82",
            "listingIds": [
                "588e01488b66181000065ca1"
            ],
            "enabled": false,
            "filters": [
                {
                    "value": true,
                    "operator": "$eq",
                    "field": "review.shouldReview",
                    "passThrough": true,
                    "_id": "595cf0fe6e327d1000cac403"
                },
                {
                    "value": false,
                    "operator": "$exists",
                    "field": "review.hasGuestReviewed",
                    "passThrough": true,
                    "_id": "595cf0fe6e327d1000cac402"
                }
            ],
            "action": "send platform message",
            "target": "guest",
            "when": "5 days",
            "trigger": "check out",
            "humanRepresentation": "Send platform message to guest 5 days after check out ONLY IF the guest should be reviewed for this reservation & the guest had not already reviewed the booking",
            "name": "Review Reminder - Second",
            "platform": {
                "body": "Hey {{guest_first}},\n\nWe are sorry for asking you this again!"
            }
        }
    ]
}

HTTP Request

GET /hooks

Query Parameters

Parameter Default Description Example
listingId null Limit to a specific listing 531968414930a7f09b075800
fields null Selection of fields, separated by space createdAt
sort -createdAt Field to sort by. Prepend - for DESC. createdAt
limit 25 Pagination, max: 100 25
skip 0 Pagination 0

Response

The requested Hook objects

Create a hook

Response

{
  "accountId": "596f6fe706112710005d96ff"
  "action": "send sms"
  "enabled": true
  "humanRepresentation": "Send sms to Peter on booking confirmation"
  "listingIds": ["5d14d253765308001fcb596c"]
  "name": "Confirmation Hook 1"
  "sms": {
    "body": "Hi! Will be a pleasure to host you!"
    }
  "target": "user"
  "to": {
    "userId": "5d48a21cdda60600237e0647"
    }
  "trigger": "reservation confirmed"
  "useNoReply": false
  "when": 0
  "_id": "5e15cba268f6200025c4d36a"
}

HTTP Request

POST /hooks

Body

Parameter Type Default Example
accountId String (ObjectId) null
listingIds Array of String (ObjectId) null
excludeListingIds Array of String (ObjectId) null
enabled Boolean true
filters Array of Filters null
action String - Required receptionists dashboard, send platform message, send email, post bookings dashboard, send sms, internal notes
target String
when Required 0
replyTo String
useNoReply Boolean False
trigger String - Required before confirmed, reservation created, reservation reserved, reservation declined, reservation closed, new inquiry, reservation confirmed, reservation altered, reservation canceled, check in, check out
to Required
email Required for send email action
sms Required for send sms action
platform Required for send platform message action
task Required for receptionists dashboard, post bookings dashboard actions

Example

Body

{action: "send sms", email: {}, enabled: true, excludeListingIds: [], listingIds: ["5d14d253765308001fcb596c"], name: "Confirmation Hook 1", sms: {body: "Hi! Will be a pleasure to host you!"}, target: "user", to: {userId: "5d48a21cdda60600237e0647"}, trigger: "reservation confirmed", when: 0, whenUnit: "days", whenValue: 1}

Response

The inserted object.

Retrieve a hook

HTTP Request

GET /hooks/:id

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space ``

Response

The requested Hook object.

Update a hook

HTTP Request

PUT /hooks/:id

Body

All hook fields are editable

Response

The updated object.

Delete a hook

HTTP Request

DELETE /hooks/:id

Response

OK

Inbox - Guest conversations

Conversation object

{
    "_id": "5815f92df4ff4b0f005f053b",
    "createdAt": "2016-10-30T13:44:13.031Z",
    "lastUpdatedAt": "2017-07-31T07:03:31.685Z",
    "isStarred": true,
    "isRead": true,
    "assignee": "59749d2537278b0f00396943",
    "readLog": [
        {
            "by": "587b8283fc6b2610000f9b39",
            "_id": "587c94ac66e78f10003ebff3",
            "at": "2017-01-16T09:38:52.237Z"
        },
        {
            "by": "591c23fddbb50f1000fa17ff",
            "_id": "591c514455392d280059964a",
            "at": "2017-05-17T13:33:56.815Z"
        }
    ],
    "pendingTasks": [],
    "accountId": "563e0b6a08a2710e00057b82",
    "integration": {
        "_id": "5784a3cc64ce9c0e00ecaf1e",
        "platform": "airbnb",
        "airbnb": {
            "id": 12345,
            "guestId": 12345,
        },
    }
    "thread": [
        {
            "module": "sms",
            "createdAt": "2017-07-31T07:03:31.685Z",
            "sentAt": "2017-07-31T07:04:52.312Z",
            "status": "completed",
            "isAutomatic": true,
            "reservationId": "5976e738739d2d0f008fe0d8",
            "by": "Us",
            "sms": {
                "from": "447520619995",
                "to": [
                    "353858767622"
                ],
                "body": "Hey just making sure you got this SMS"
            }
        }
    ]
}
Attribute Type Description
_id String Unique id
accountId ObjectId(Account) Unique id
userId ObjectId(User) Unique id
integration Object (see below)
guestId String Unique id
ownerId ObjectId(Owner) Unique id
ownerReservationId ObjectId(Owner's Reservation) Unique id
pendingTasks [pendingTask] (see below)
thread [thread] (see below)
contact Mixed tipe contact info
conversationWith String Contact, Guest, User, owner
subject String
assignee String Unique id
isRead Boolean
isStarred Boolean
readLog [readLog]
createdAt Date
lastUpdatedAt Date
lastModifiedAt Date
lastUpdatedFromGuest Date
lastSyncedAt Date
language String
firstReceptionist String
assignee ObjectId(User) Unique id
isStarred Boolean
isRead Boolean
status Enum OPEN, SNOOZED, ARCHIVED
priority Number
snoozedUntil Date
meta Object (see below)

The integration object

{
    "integration": {
        "_id": "5784a3cc64ce9c0e00ecaf1e",
        "platform": "airbnb",
        "airbnb": {
        "id": 12345,
        "guestId": 12345,
    },
    },
}
Attribute Type Description
_id String Unique id
platform String airbnb, airbnb2, homeaway, rentalsUnited,
airbnb Object
---id Number Id from channel
---guestId Number Guest id from channel
airbnb2 Object
---id Number Id from channel
---guestId Number Guest id from channel
homeaway Object
---id Number Id from channel
rentalsUnited Object
---id Number Id from channel

The pendingTasks object

{
    "pendingTasks": {
        "mqId": "49727fd5-936a-47r6-9c0c-7664a97c3fc1",
        "platform": "airbnb",
        "description": "Sync conversation",
        "createdAt": "2017-01-01T00:00:00.640Z",
        "error": "Missing thread identifier"
    },
}
Attribute Type Description
mqId String Unique id
platform String airbnb, airbnb2, homeaway, rentalsUnited,
description String
createdAt Date
error String

The thread object

{
    "thread": [
        {
            "module": "sms",
            "createdAt": "2017-07-31T07:03:31.685Z",
            "sentAt": "2017-07-31T07:04:52.312Z",
            "status": "completed",
            "isAutomatic": true,
            "reservationId": "5976e738739d2d0f008fe0d8",
            "by": "Us",
            "sms": {
                "from": "447520619995",
                "to": [
                    "353858767622"
                ],
                "body": "Hey just making sure you got this SMS"
            }
        }
    ]
}
Attribute Type Description
_id String Unique id
module Enum airbnb, email, sms, rentalsUnited, note
createdAt Date
sentAt Date
shouldBeSentAt Date
status enum pending, completed, error
error String
isAutomatic Boolean
reservationId ObjectId (Reservation)
sms Object (see below)
email Object (see below)
airbnb Object (see below)
note Object (see below)

The email object

{
    "email": {
        "from": "BnbAir <example@user.guesty.com>",
        "to": [
            "example@gmail.com"
        ],
        "subject": "This is the subject",
        "body": "This is the body"
    }
}
Attribute Type Description
from String
to Array (String)
cc Array (String) Array of emails to send this email in cc
bcc Array (String) Array of emails to send this email in bcc
subject String Subject line for the email
body String Text of message, html format
attachments Array of attachments

The sms object

{
    "sms": {
        "from": "447520619995",
        "to": [
            "353858767622"
        ],
        "body": "Hey just making sure you got this SMS"
    }
}
Attribute Type Description
from String Source phone
to Array (String) Phone targets
body String Text of message, plain format

The airbnb object

{
    "airbnb": {
        "body": "Hey Host,\n\nOwer trip was perfect!"
    }
}
Attribute Type Description
body String Text of message, plain format

The note object

{
    "note": {
        "body": "this is a note"
    }
}
Attribute Type Description
body String Text of message, plain format

The readLog object

{
    "readLog": [
        {
            "by": "587b8283fc6b2610000f9b39",
            "_id": "587c94ac66e78f10003ebff3",
            "at": "2017-01-16T09:38:52.237Z"
        }
    ]
}
Attribute Type Description
_id String Unique id
by ObjectId (User) Unique Id
at Date String

The meta object

{
    "meta": {
    "guestName": "Smith",
    "reservations": [
            {
            "_id": "5e2889p499a691401e2e1d03",
            "confirmationCode": "AAAAAAAAA",
            "checkIn": "2020-02-18T14:00:00.000Z",
            "checkOut": "2020-02-19T10:00:00.000Z"
            }
        ]
    }   
}
Attribute Type Description
guestName String
reservations [reservation] (see below)

The reservation object

Attribute Type Description
_id ObjectId (reservation) Unique Id
confirmationCode String
checkIn Date
checkOut Date

List all conversations

{
    "results": [
        {
            "_id": "59664e2a41e0311000598518",
            "createdAt": "2017-07-12T16:28:26.613Z",
            "lastUpdatedAt": "2017-07-12T16:28:45.381Z",
            "isRead": false,
            "readLog": [],
            "pendingTasks": [],
            "accountId": "563e0b6a08a2710e00057b82",
            "integrationId": "5784a3cc64ce9c0e00ecaf1e",
            "thread": [
                {
                    "module": "email",
                    "createdAt": "2017-07-12T16:28:45.381Z",
                    "sentAt": "2017-07-12T16:28:48.095Z",
                    "status": "completed",
                    "by": "Us",
                    "email": {
                        "from": "BnbAir <orisee88126@user.guesty.com>",
                        "to": [
                            "sheliami@guesty.com"
                        ],
                        "subject": "Hey",
                        "body": "<p>This is a testy</p>\n"
                    }
                }
            ]
        }
    ],
    "count": 1,
    "fields": "",
    "limit": 10,
    "skip": 0
}

HTTP Request

GET /inbox/conversations

Query Parameters

Parameter Default Description Example
accountId --- Optional with admin token, Unavailable with user token. 531968414930a7f09b075800
guestId null Filter by specific guest 531968414930a7f09b075800
reservationId null Filter by specific reservation 531968414930a7f09b075800
fields null Selection of fields, separated by space thread
sort createdAt; completedAt in completed mode Sorting lastUpdatedAt
limit 25 Pagination, max: 100 25
skip 0 Pagination 0

Response

Conversation objects.

Retrieve a conversation

{
    "_id": "59229452b4380d1000d52090",
    "createdAt": "2017-05-22T07:33:38.973Z",
    "lastUpdatedAt": "2017-06-04T13:39:21.395Z",
    "isRead": true,
    "assignee": "5803d02f7f2b400f00f0d471",
    "readLog": [
        {
            "by": "591c23fddbb50f1000fa17ff",
            "_id": "595a0595a8ec43100042dd70",
            "at": "2017-07-03T08:51:33.326Z"
        }
    ],
    "pendingTasks": [],
    "accountId": "563e0b6a08a2710e00057b82",
    "integrationId": "5784a3cc64ce9c0e00ecaf1e",
    "thread": [
        {
            "module": "note",
            "createdAt": "2017-06-04T13:39:21.395Z",
            "by": "Us",
            "note": {
                "body": "Requested a wake up call @12"
            }
        }
    ]
}

HTTP Request

GET /inbox/conversations/:id

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space. When null retrieve the main properties of the object. We recommend always specifying the specific fields you'd like to receive to ensure that you get them. Please see the full list above. "thread"

Response

Conversation object.

Post a new message to conversation

Response

{
    "_id": "5919be619e2b4210006f5ef7",
    "createdAt": "2017-05-15T14:42:41.435Z",
    "lastUpdatedAt": "2017-09-13T15:23:39.342Z",
    "isStarred": true,
    "isRead": true,
    "assignee": "580c817ed4b70d0f00dcf6f6",
    "readLog": [
        {
            "by": "580c817ed4b70d0f00dcf6f6",
            "_id": "599d33837bd4aa0f0015218e",
            "at": "2017-08-23T07:49:23.990Z"
        }
    ],
    "pendingTasks": [],
    "accountId": "563e0b6a08a2710e00057b82",
    "integrationId": "5784a3cc64ce9c0e00ecaf1e",
    "thread": [
        {
            "module": "sms",
            "createdAt": "2017-09-13T15:23:39.342Z",
            "status": "pending",
            "by": "Us",
            "sms": {
                "from": "447520619995",
                "to": [
                    "972502938411"
                ],
                "body": "HEY!"
            }
        },
        {
            "module": "sms",
            "createdAt": "2017-09-11T20:42:23.166Z",
            "sentAt": "2017-09-11T20:42:24.956Z",
            "status": "completed",
            "by": "Us",
            "sms": {
                "from": "447520619995",
                "to": [
                    "972502938411"
                ],
                "body": "alsie"
            }
        }
    ]
}

HTTP Request

POST /inbox/conversations

Body

Parameter Default
conversationId Required
module Required
email Required for email module
sms Required for sms module

Example

Body

{"conversationId":"5919be619e2b4210006f5ef7","module":"sms","email":{},"sms":{"body":"HEY!"}}

Response

The created object.

Inbox - Owner conversations

Conversation object

{
    "accountId": "5b852676354b34003f0a55eb",
    "isRead": true,
    "lastUpdatedAt": "2020-01-09T10:03:07.518Z",
    "owner": {
        "email": "hagar@guesty.com",
        "firstName": "Hagar",
        "fullName": "Hagar Sened",
        "lastName": "Sened",
        "phone": "+97222222222",
        "_id": "5d00c7b3591940001f8835fb"
    },
    "ownerId": "5d00c7b3591940001f8835fb",
    "ownerReservationId": "5e16fa5bd5bea5001f83abbd",
    "thread": [
        {
            "by": "Us",
            "createdAt": "2020-01-09T10:03:07.518Z",
            "module": "note",
            "note": {
                "body": "Hagar Sened has reserved MAZ74 from Jan 30, 2020 at 03:00 PM until Jan 31, 2020 at 11:00 AM"
            }
        }
    ],
    "_id": "5e16fa5bd5bea5001f83abca"
}
Attribute Type Description
_id String Unique id
accountId String (ObjectId)
isRead Boolean
lastUpdatedAt Date
owner Owner object (see below)
ownerId String (ObjectId)
ownerReservationId String (ObjectId)
thread [thread] (see below)
readLog [readLog] (see below)

The owner object

{
    "owner": {
        "email": "hagar@guesty.com",
        "firstName": "Hagar",
        "fullName": "Hagar Sened",
        "lastName": "Sened",
        "phone": "+97222222222",
        "_id": "5d00c7b3591940001f8835fb"
    }
}
Attribute Type
_id String (ObjectId)
email String
phone String
notes String
firstName String
lastName String
fullName String

The thread object

{
    "thread": [
        {
            "by": "Us",
            "createdAt": "2020-01-09T10:03:07.518Z",
            "module": "note",
            "note": {
                "body": "Hagar Sened has reserved MAZ74 from Jan 30, 2020 at 03:00 PM until Jan 31, 2020 at 11:00 AM"
            }
        }
    ]
}
Attribute Type Description
_id String (ObjectId) Unique id
module Enum airbnb, email, sms, rentalsUnited, note
type Enum fromHost, fromGuesty
createdAt Date
sentAt Date
shouldBeSentAt Date
status enum pending, completed, error
error String
isAutomatic Boolean
reservationId ObjectId (Reservation)
sms Object (see below)
email Object (see below)
airbnb Object (see below)
rentalsUnited Object (see below)
note Object (see below)

The email object

{
    "email": {
        "from": "BnbAir <example@user.guesty.com>",
        "to": [
            "example@gmail.com"
        ],
        "subject": "This is the subject",
        "body": "This is the body"
    }
}
Attribute Type Description
from String
to Array (String)
cc Array (String) Array of emails to send this email in cc
bcc Array (String) Array of emails to send this email in bcc
subject String Subject line for the email
body String Text of message, html format
attachments Array of attachments

The sms object

{
    "sms": {
        "from": "447520619995",
        "to": [
            "353858767622"
        ],
        "body": "Hey just making sure you got this SMS"
    }
}
Attribute Type Description
from String Source phone
to Array (String) Phone targets
body String Text of message, plain format

The airbnb object

{
    "airbnb": {
        "body": "Hey Host,\n\nOwer trip was perfect!"
    }
}
Attribute Type Description
body String Text of message, plain format

The rentalsUnited object

{
    "rentalsUnited": {
        "body": "Hey Host,\n\nOwer trip was perfect!"
    }
}
Attribute Type Description
body String Text of message, plain format

The note object

{
    "note": {
        "body": "this is a note"
    }
}
Attribute Type Description
body String Text of message, plain format

The readLog object

{
    "readLog": [
        {
            "by": "587b8283fc6b2610000f9b39",
            "_id": "587c94ac66e78f10003ebff3",
            "at": "2017-01-16T09:38:52.237Z"
        }
    ]
}
Attribute Type Description
_id String Unique id
by ObjectId (User) Unique Id
at Date String

List all conversations

{
    "results": [
        {
            "accountId": "5b852676354b34003f0a55eb",
            "isRead": true,
            "lastUpdatedAt": "2019-10-02T10:03:07.518Z",
            "owner": {
                "email": "hagar@guesty.com",
                "firstName": "Hagar",
                "fullName": "Hagar Sened",
                "lastName": "Sened",
                "phone": "+97222222222",
                "_id": "5d00c7b3591940001f8835fb"
            },
            "ownerId": "5d00c7b3591940001f8835fb",
            "ownerReservationId": "5e16fa5bd5bea5001f83abbd",
            "readLog": [
                {
                    "by": "591c23fddbb50f1000fa17ff",
                    "_id": "595a0595a8ec43100042dd70",
                    "at": "2019-10-02T10:03:07.518Z"
                }
            ],
            "thread": [
                {
                    "by": "Us",
                    "createdAt": "2019-10-02T10:03:07.518Z",
                    "module": "note",
                    "note": {
                        "body": "Hagar Sened has reserved MAZ74 from Jan 30, 2020 at 03:00 PM until Jan 31, 2020 at 11:00 AM"
                    }
                }
            ],
            "_id": "5e16fa5bd5bea5001f83abca"
        }
    ],
    "count": 1,
    "fields": "",
    "limit": 10,
    "skip": 0
}

HTTP Request

GET /owner-inbox/conversations

Query Parameters

Parameter Default Description Example
accountId --- Optional with admin token, Unavailable with user token. 531968414930a7f09b075800
ownerId null Filter by specific owner 531968414930a7f09b075800
reservationId null Filter by specific reservation 531968414930a7f09b075800
fields null Selection of fields, separated by space thread
sort -lastUpdatedAt; Prepend - to get the results in descending order Sorting lastUpdatedAt
limit 10 Pagination, max: 100 25
skip 0 Pagination 0

Response

Conversation objects.

Retrieve a conversation

{
    "_id": "59229452b4380d1000d52090",
    "createdAt": "2017-05-22T07:33:38.973Z",
    "lastUpdatedAt": "2017-06-04T13:39:21.395Z",
    "isRead": true,
    "assignee": "5803d02f7f2b400f00f0d471",
    "readLog": [
        {
            "by": "591c23fddbb50f1000fa17ff",
            "_id": "595a0595a8ec43100042dd70",
            "at": "2017-07-03T08:51:33.326Z"
        }
    ],
    "pendingTasks": [],
    "accountId": "563e0b6a08a2710e00057b82",
    "integrationId": "5784a3cc64ce9c0e00ecaf1e",
    "thread": [
        {
            "module": "note",
            "createdAt": "2017-06-04T13:39:21.395Z",
            "by": "Us",
            "note": {
                "body": "Requested a wake up call @12"
            }
        }
    ]
}

HTTP Request

GET /owner-inbox/conversations/:id

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space. When null retrieve the main properties of the object. We recommend always specifying the specific fields you'd like to receive to ensure that you get them. Please see the full list above. "thread"

Response

Conversation object.

Post a new message to conversation

Response

{
    "accountId" "5b852676354b34003f0a55eb"
    "conversationWith": "owner",
    "createdAt": "2020-01-09T10:03:07.518Z",
    "isRead": true,
    "language": "en",
    "lastModifiedAt": "2020-01-09T11:57:55.210Z",
    "lastUpdatedAt": "2020-01-09T11:57:55.208Z",
    "lastUpdatedFromGuest": "2020-01-09T10:03:07.518Z",
    "meta": {
        "reservations": []
    },
    "reservations": [],
    "ownerId": "5d00c7b3591940001f8835fb",
    "ownerReservationId": "5e16fa5bd5bea5001f83abbd",
    "pendingTasks": [],
    "priority": 10,
    "readLog": [],
    "snoozedUntil": null,
    "subject": "Hagar Sened has reserved MAZ74 from Jan 30, 2020 at 03:00 PM until Jan 31, 2020 at 11:00 AM...",
    "thread": [
        {
            "by": "Us",
            "createdAt": "2020-01-09T11:57:55.208Z",
            "module": "note",
            "note": {
                "body": "HEY!"
            }
        },
        {
            "by": "Us",
            "createdAt": "2020-01-09T10:03:07.518Z",
            "module": "note",
            "note": {
                "body": "Hagar Sened has reserved MAZ74 from Jan 30, 2020 at 03:00 PM↵            until Jan 31, 2020 at 11:00 AM"
            }
        }
    ],
    "__v": 8,
    "_id": "5919be619e2b4210006f5ef7"
}

HTTP Request

POST /owner-inbox/conversations

Body

Parameter Default
conversationId Required
module Required
email Required for email module
sms Required for sms module
note Required for notes module

Example

Body

{"conversationId":"5919be619e2b4210006f5ef7","module":"note","note":{"body":"HEY!"}}

Response

The created object.

Update conversation

HTTP Request

PUT /owner-inbox/conversations/:id

Body

All conversation fields are editable limited by Role's permissions

Response

The updated object.

Set conversation read by user

HTTP Request

POST /owner-inbox/conversations/:id/read

Response

OK

Inbox v2 - Guest conversations

The conversation object

{
    "_id": "5815f92df4ff4b0f005f053b",
    "createdAt": "2020-06-30T13:44:13.031Z",
    "updatedAt": "2020-07-31T07:03:31.685Z",
    "modifiedAt": "2020-07-31T07:03:31.685Z",
    "assignee": {
        "_id": "59749d2537278b0f00396943",
        "fullName": "John",
        "isAssignedToGCS": true,
    },
    "type": "guest",
    "subject": "Thank you",
    "state": { 
        "lastMessage": "Hi, it's very nice to meet you!",
        "date": "2020-07-31T07:03:31.685Z",
        "recipients": [],
    },
    "pendingTasks" : [],   
    "accountId": "563e0b6a08a2710e00057b82",
    "meta": {
        "reservations":[
            {
                "_id": "5784a3cc64ce9c0e00ecaf1g",
                "status": "inquiry",
                "listing": {
                    "_id": "5784a3cc64ce9c0e00eca3qq",
                }
            }
        ],
         "integration": {
            "_id": "5784a3cc64ce9c0e00ecaf1e",
            "platform": "airbnb2",
            "externalId": 123456,
        },
        "guest":{
            "_id" :"5784a3cc64ce9c0e00eca3qb",
            "fullName" : "Adam",
            "isReturning" : false
        }
    }
}
Attribute Type Description
_id ObjectId Unique id
accountId ObjectId(Account) Unique id
createdAt Date supported in sort
updatedAt Date
modifiedAt Date supported in sort
lastSyncedAt Date
lastMessageFrom Object (see below)
assignee Object (see below)
type String guest, user, contact
subject String
state Object (see below)
priority Number
pendingTasks [pendingTask] (see below)
firstReceptionist String
meta Object (see below)
internal Object (see below)
hasFailedPost Boolean
communicationMethods String airbnb, airbnb2, email, sms, tripAdvisor, whatsapp
conversationExternalId String Unique id for chanel communication

The lastMessageFrom object

{
    "lastMessageFrom": {
        "user": "2020-07-31T07:03:31.685Z",
        "nonUser": "2020-07-31T07:03:31.685Z",
        "whatsapp": "2020-07-31T07:03:31.685Z",
    },
}
Attribute Type Description
user Date
nonUser Date
whatsapp Date

The assignee object

{
    "assignee": {
        "_id": "59749d2537278b0f00396943",
        "fullName": "John",
        "isAssignedToGCS": true,
    },
}
Attribute Type Description
_id ObjectId Unique id, default is null
fullName String
picture Object (see below)
isAssignedToGCS Boolean

The state object

{
    "state": { 
        "lastMessage": {
            "body": "Hi, it's very nice to meet you!",
            "date": "2020-07-31T07:03:31.685Z",
        },
        "recipients": [],
    },
}
Attribute Type Description
lastMessage Object
--body String
--date Date
recipients [recipient] (see below)

The recipient object

{
    "state": { 
        "lastMessage": {
            "body": "Hi, it's very nice to meet you!",
            "date": "2020-07-31T07:03:31.685Z",
        },
        "recipients": [],
    },
}
Attribute Type Description
recipientId ObjectId Unique id
type String guest, user, contact, gse
read Boolean
counter Number count of unread posts
status String open, snoozed, archived
snoozedUntil Date

The pendingTasks object

{
    "pendingTasks": {
        "mqId": "49727fd5-936a-47r6-9c0c-7664a97c3fc1",
        "platform": "airbnb",
        "description": "Sync conversation",
        "createdAt": "2017-01-01T00:00:00.640Z",
        "error": "Missing thread identifier"
    },
}
Attribute Type Description
mqId String Unique id
platform String airbnb, airbnb2, homeaway, rentalsUnited,
description String
createdAt Date
error String

The meta object

{
    "meta": {
        "reservations":[
            {
                "_id": "5784a3cc64ce9c0e00ecaf1g",
                "status": "inquiry",
                "listing": {
                    "_id": "5784a3cc64ce9c0e00eca3qq",
                }
            }
        ],
        "integration": {
            "_id": "5784a3cc64ce9c0e00ecaf1e",
            "platform": "airbnb2",
            "externalId": 123456,
        },
        "guest":{
            "_id" :"5784a3cc64ce9c0e00eca3qb",
            "fullName" : "Adam",
            "isReturning" : false
        }
    }
}
Attribute Type Description
reservations [reservation] (see below)
integration Object (see below)
guest Object (see below)

The reservation object

Attribute Type Description
_id ObjectId (reservation) Unique Id
confirmationCode String
status String
checkIn Date
checkOut Date
listing Object
--id ObjectId (listing) Unique Id

The integration object

Attribute Type Description
_id ObjectId (integration) Unique Id
fullName String
externalId String only for airbnb integrations

The guest object

Attribute Type Description
_id ObjectId (guest) Unique Id
platform String airbnb, airbnb2, homeaway, rentalsUnited
isReturning Boolean

The internal object

{
    "internal": {
        "notificationId": "5784a3cc64ce9c0e00eca3q71",
        "language": "EN",
    },
}
Attribute Type Description
notificationId ObjectId Unique id
language String

The post object

{
    "_id": "5f06e08bc5d898002ac05313",
    "conversationId": "5815f92df4ff4b0f005f053b",
    "module": {
        "to": [],
        "cc": [],
        "bcc": [],
        "templateValues": [],
        "type": "sms",
        "reservationId": "5784a3cc64ce9c0e00ecaf1g",
        "toNumber": "447520617777",
        "fromNumber": "447520619999"
    },
    "from": {
        "_id": "5e737c73d3979d00293b3b50",
        "fullName": "User name",
        "type": "user"
    },
    "body": "Hi, it's very nice to meet you!",
    "status": "completed",
    "sentBy": "host",
    "createdAt": "2020-07-09T09:16:59.886Z",
    "attachments": [],
}
Attribute Type Description
_id ObjectId Unique id
module Object (see below)
body String
createdAt Date
sentAt Date
shouldBeSentAt Date
attachments: [attachment] (see below) only receiving is supported
status String pending, completed, failed
error String
isAutomatic Boolean
sentBy String guest, host, guesty, thirdparty, contact, log, channel
from Object
--id ObjectId (user, employee) Unique id
--type String user, employee
--fullName String
conversationExternalId String

The attachment object

Attribute Type Description
attachmentUrl String
origFileName String
type String
size String
contentName String

Get all conversations

{    
    "status": 200,
        "data": {
        "conversations": [
            {
                "_id": "5815f92df4ff4b0f005f053b",
                "createdAt": "2020-06-30T13:44:13.031Z",
                "updatedAt": "2020-07-31T07:03:31.685Z",
                "modifiedAt": "2020-07-31T07:03:31.685Z",
                "assignee": {
                    "_id": "59749d2537278b0f00396943",
                    "fullName": "John",
                    "isAssignedToGCS": true,
                },
                "type": "guest",
                "subject": "Thank you",
                "state": { 
                    "lastMessage": "Hi, it's very nice to meet you!",
                    "date": "2020-07-31T07:03:31.685Z",
                    "recipients": [],
                },
                "pendingTasks" : [],   
                "accountId": "563e0b6a08a2710e00057b82",
                "meta": {
                    "reservations":[
                        {
                            "_id": "5784a3cc64ce9c0e00ecaf1g",
                            "status": "inquiry",
                            "listing": {
                                "_id": "5784a3cc64ce9c0e00eca3qq",
                            }
                        }
                    ],
                    "integration": {
                        "_id": "5784a3cc64ce9c0e00ecaf1e",
                        "platform": "airbnb2",
                        "externalId": 123456,
                    },
                    "guest":{
                        "_id" :"5784a3cc64ce9c0e00eca3qb",
                        "fullName" : "Adam",
                        "isReturning" : false
                    }
                }
            }
        ],
        "countUnread": 100,
        "fields": "guest reservation status assignee priority createdAt",
        "limit": 1,
        "cursor": {
            "after": "",
            "before": "MjAyMC0wNy0xMFQxMDoyMToxMy4yODNaXzVmMDg0MTE5MjhlZjlmMDAyODJjMTVhYg==",
        }
    }
}

HTTP Request

GET /communication/conversations

Authorization

Only accessible to Admin or User tokens. accountId is taken from token and not from request.

Query Parameters

Parameter Default Description Example
filters Array of filters to query by (See below) [{"field":"status", "operator":"$eq", "value": "OPEN"}]
fields Selection of fields, separated by space guest reservation status assignee priority createdAt
sort -createdAt Sorting -modifiedAt
limit 25 Pagination, max: 100 25
cursorAfter '' Pagination MjAyMC0wNy0wOVQxMDowMzozOS43ODBaXzVmMDZlYjdiYzVkODk4MDAyYWMwNTM2Nw==
cursorBefore null Pagination MjAyMC0wNy0xMFQxMDoyMToxMy4yODNaXzVmMDg0MTE5MjhlZjlmMDAyODJjMTVhYg==

Filters

{
    "field": "read",
    "operator": "$eq",
    "value": false,
}
Parameter Default Description Example
field Required Subject of the filter status, guest._id, reservation._id, reservation.status, read, assignee._id, listing._id
operator Required Enhanced MongoDB comparison operator: $eq, $exists, $not, $contains, $notcontains, $gt, $lt, $between, $in, $nin
value Required Value to filter by.
Filter example with UTF-8 Encoding to use from postman:

[%7B%22operator%22:%22$eq%22,%22field%22:%22reservation._id%22,%22value%22:%225f3526b99d4d1d00291ae185%22%7D]

Cursor pagination

   "cursor": {
            "after": "MjAyMC0wNy0wOVQxMDowMzozOS43ODBaXzVmMDZlYjdiYzVkODk4MDAyYWMwNTM2Nw==",
            "before": "jAyMC0wNy0xMFQxMDoyMToxMy4yODNaXzVmMDg0MTE5MjhlZjlmMDAyODJjMTVhYg==",
        }

Response

Conversation objects.

Get conversation

{
    "status": 200,
    "data": {
        "_id": "5815f92df4ff4b0f005f053b",
        "createdAt": "2020-06-30T13:44:13.031Z",
        "updatedAt": "2020-07-31T07:03:31.685Z",
        "modifiedAt": "2020-07-31T07:03:31.685Z",
        "assignee": {
            "_id": "59749d2537278b0f00396943",
            "fullName": "John",
            "isAssignedToGCS": true,
        },
        "type": "guest",
        "subject": "Thank you",
        "state": { 
            "lastMessage": "Hi, it's very nice to meet you!",
            "date": "2020-07-31T07:03:31.685Z",
            "recipients": [],
        },
        "pendingTasks" : [],   
        "accountId": "563e0b6a08a2710e00057b82",
        "meta": {
            "reservations":[
                {
                    "_id": "5784a3cc64ce9c0e00ecaf1g",
                    "status": "inquiry",
                    "listing": {
                        "_id": "5784a3cc64ce9c0e00eca3qq",
                    }
                }
            ],
            "integration": {
                "_id": "5784a3cc64ce9c0e00ecaf1e",
                "platform": "airbnb2",
                "externalId": 123456,
            },
            "guest":{
                "_id" :"5784a3cc64ce9c0e00eca3qb",
                "fullName" : "Adam",
                "isReturning" : false
            }
        }
    }
}

HTTP Request

GET /communication/conversations/:id

Authorization

Only accessible to Admin or User tokens. accountId is taken from token and not from request.

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space. When null retrieve the main properties of the object. We recommend always specifying the specific fields you'd like to receive to ensure that you get them. Please see the full list above. status

Response

Conversation object.

Get posts by conversation id

{
    "status": 200,
    "data": {
        "posts": [
            {
                "_id": "5f06e08bc5d898002ac05313",
                "conversationId": "5815f92df4ff4b0f005f053b",
                "module": {
                    "to": [],
                    "cc": [],
                    "bcc": [],
                    "templateValues": [],
                    "type": "sms",
                    "reservationId": "5784a3cc64ce9c0e00ecaf1g",
                    "toNumber": "447520617777",
                    "fromNumber": "447520619999"
                },
                "from": {
                    "_id": "5e737c73d3979d00293b3b50",
                    "fullName": "User name",
                    "type": "user"
                },
                "body": "Hi, it's very nice to meet you!",
                "status": "completed",
                "sentBy": "host",
                "createdAt": "2020-07-09T09:16:59.886Z",
                "attachments": [],
            }
        ],
        "count": 1,
        "cursor": {
            "after": "MjAyMC0wNy0wOVQxMDowMzozOS43ODBaXzVmMDZlYjdiYzVkODk4MDAyYWMwNTM2Nw==",
            "before": "MjAyMC0wNy0xMFQxMDoyMToxMy4yODNaXzVmMDg0MTE5MjhlZjlmMDAyODJjMTVhYg==",
        }
    }
}

HTTP Request

GET /communication/conversations/:id/posts

Authorization

Only accessible to Admin or User tokens. accountId is taken from token and not from request.

Query Parameters

Parameter Default Description Example
sort -createdAt Sorting -createdAt
limit 25 Pagination, max: 100 25
cursorAfter '' Pagination MjAyMC0wNy0wOVQxMDowMzozOS43ODBaXzVmMDZlYjdiYzVkODk4MDAyYWMwNTM2Nw==
cursorBefore null Pagination MjAyMC0wNy0xMFQxMDoyMToxMy4yODNaXzVmMDg0MTE5MjhlZjlmMDAyODJjMTVhYg==

cursorAfter and cursorBefore are not allowed to be used at the same time in one request.

Response

Post object.

Add new message to conversation without sending it

{
    "status": 200,
    "data": {
        "module": {
            "to": [],
            "cc": [],
            "bcc": [],
            "templateValues": [],
            "type": "email"
        },
        "_id": "5f465cea933726002b6f414b",
        "body": "Add message without sending",
        "conversationId": "5815f92df4ff4b0f005f053b",
        "createdAt": "2020-08-26T13:00:26.329Z",
        "attachments": [],
    }
}

HTTP Request

POST /communication/conversations/:id/posts

Body

Parameter Default Description
module Required
--type Required sms, email, note, log, whatsapp, airbnb2
body Required The message itself
sentBy host host, guest

Authorization

Only accessible to Admin or User tokens. accountId is taken from token and not from request.

Example

Body

{"module":{"type":"note"},"body":"This is new note"}

Response

The created object.

Send new message

{
    "status": 200,
    "data": {
        "module": {
            "to": [],
            "cc": [],
            "bcc": [],
            "templateValues": [],
            "type": "email"
        },
        "_id": "5f465cea933726002b6f414b",
        "body": "Add message without sending",
        "conversationId": "5815f92df4ff4b0f005f053b",
        "createdAt": "2020-08-26T13:00:26.329Z",
        "attachments": [],
    }
}

HTTP Request

POST /communication/conversations/:id/send-message

Body

Parameter Default Description
module Required
--type Required platform, sms, email, note, log, whatsapp, airbnb2
--cc for email module array of email addresses
--bcc for email module array of email addresses
body Required The message itself

Module type platform posts will be sent through Airbnb for conversations with Airbnb guests and through Email for conversations with non Airbnb guests.

Authorization

Only accessible to Admin or User tokens. accountId is taken from token and not from request.

Example

Body

{"module":{"type":"sms"},"body":"This is new message"

Response

The created object.

Error objects

Validation error

Status: 400 Bad Request

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "\"conversationId\" with value \"1\" fails to match the valid mongo id pattern",
        "data": {
            "details": [
                {
                    "message": "\"conversationId\" with value \"1\" fails to match the valid mongo id pattern",
                    "path": [
                        "conversationId"
                    ],
                    "type": "string.pattern.name",
                    "context": {
                        "name": "valid mongo id",
                        "regex": {},
                        "value": "1",
                        "label": "conversationId",
                        "key": "conversationId"
                    }
                }
            ]
        }
    }
}

Forbidden error

Status: 403 Forbidden

{
    "error": {
        "code": "FORBIDDEN",
        "message": "Forbidden"
    },
    "status": 403,
    "data": {}
}

500 error

Status: 500 Internal Server Error

{
    "error": {
        "message": "Request failed with status code 500"
    },
    "status": 500,
    "data": {}
}

Billing - Invoices

Invoice object

Attribute Type Description
_id String Unique id
accountId String Id of the user owning this invoice
methodId String Id of the payment method.
method Enum Can be any supported payment method, currently only stripe. (It is here to make it permanent as method can be deleted)
methodText String Representable name of the payment method. e.g. "Visa 7243" (It is here to make it permanent as method can be deleted)
status Enum Can be succeeded or failed or fully-refunded.
amount Number The amount paid
currency Enum Any supported currency.
creditApplied Number The amount of credit that was used in this invoice.
description String Text describing the invoice.
createdAt Date The date this invoice was created.
refundedAt Date The date this invoice was last refunded, even partially.
refundedAmount Number The amount this invoice has been refunded.
receiptExtraContent String Text to add to the receipt, usually defaulted to payment method. (It is here to make it permanent.)
error String If there has been an error (status is failed) this is its description
stripe Object An external object with details of this transaction.
refundedBy String
refundedReason String

List invoices

{
    "count": 1,
    "limit": 25,
    "skip": 0,
    "results": [
        {
            "_id": "595a632a420d0d04002682b9",
            "accountId": "563e0b6a08a2710e00057b82",
            "amount": 70,
            "currency": "USD",
            "createdAt": "2017-07-03T15:30:50.164Z",
            "__v": 0,
            "creditApplied": 2,
            "status": "succeeded"
        }
    ]

HTTP Request

GET /billing/invoices

Query Parameters

Parameter Default Description Example
accountId null for admin token, connected account for user token with admin token, Unavailable with user token. 531968414930a7f09b075800
methodId null Limit results to specific payment methods. Can send an array. 531968414930a7f09b075800
include_failed true Boolean true
fields null Selection of fields, separated by space amount createdAt
sort -createdAt Field to sort by. Prepend - for DESC. createdAt
limit 25 Pagination, max: 100 25
skip 0 Pagination 0

Response

Invoice objects

Upcoming invoice

{
    "accountId": "563e0b6a08a2710e00057b82",
    "status": "upcoming",
    "amount": 28,
    "items": {
        "count": 1,
        "limit": 25,
        "skip": 0,
        "results": [
            {
                "components": [
                    {
                        "name": "SOFTWARE",
                        "planType": "RESERVATION_COMMISSION",
                        "value": 1.5,
                        "isLocked": true,
                        "_id": "588e042f8b66181000065dec",
                        "amount": 28
                    }
                ],
                "isMinimumFee": false,
                "planType": "RESERVATION_COMMISSION",
                "confirmationCode": "MEQKll3",
                "source": "Manual",
                "checkIn": "2017-06-26",
                "listing": {
                    "_id": "59213fbca3af9e1000228c09",
                    "nickname": "Nadav Test Listing",
                    "title": "Nadav's Best Awesome Listing"
                },
                "reservationId": "593903b35487aa1000944c85"
            }
        ]
    },
    "currency": "USD"
}

HTTP Request

GET /billing/invoices/upcoming

Used to get the customer upcoming invoices for each of his payment methods It is a little different since it is not really an invoice object yet. Invoices are created only upon payment. Also unlike invoices/list, each invoice also has its invoice items. Pagination is also available.

Query Parameters

Parameter Default Description Example
methodId --- Required Limit results to the invoice of specific payment method. null for unassociated method's invoice (in case there is no payment method). 531968414930a7f09b075800
limit 10 Pagination for invoice items 10
skip 0 Pagination for invoice items 0

Response

List of invoice-like objects, where each item is a different payment method. status is pending. Not included fields are creditApplied, createdAt, paidAt, refundedAt, refundedAmount, receiptExtraContent, error, stripe.

The items object

Attribute Type Description
count Number Total count of results
skips Number Amount of results to skip
limit Number Maximum number of invoice items to include in this object, always 10. For more, use invoice items.list
results Array Array of invoice item objects

Download invoices receipts as pdf

HTTP Request

POST /billing/invoices/download.pdf

Body

Parameter Default Description Example
invoiceId --- Required What invoices to download. Can send an array. 531968414930a7f09b075800

Response

PDF file of receipts (use pages for multiple receipts) with download headers.

Email invoices

HTTP Request

POST /billing/invoices/email

Sends an email with attached receipt PDF file of receipts (use pages for multiple receipts).

Query Parameters

Parameter Default Description Example
invoiceId --- Required What invoices to download. Can send an array. 531968414930a7f09b075800
recipient --- Required The email of the recipient. Format Name <email>. Koby <koby@guesty.com>
message `` A message to be included in the email. See attached receipt

Response

OK

Retrieve an invoice

{
    "_id": "595a632a420d0d04002682b9",
    "accountId": "563e0b6a08a2710e00057b82",
    "amount": 0,
    "currency": "USD",
    "createdAt": "2017-07-03T15:30:50.164Z",
    "__v": 0,
    "creditApplied": 2,
    "status": "succeeded"
}

HTTP Request

GET /billing/invoices/:id

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space "amount currency"

Response

Invoice object

Update an invoice

HTTP Request

PUT /billing/invoices/:id

Body Parameters

Parameter Default Description Example
receiptExtraContent --- Update the extra content that is added to the receipt. Guesty Inc.
refundedAmount --- Used to refund a receipt. This is the amount to refund now. Maximum is the amount-(current)refundedAmount. 20
logExtraContent --- Text that will be added to the update action. For instance, refund reason. Refund - Unsatisfied

Response

Updated invoice object

Billing - Invoice Items

Invoice item object

{
    "_id": "586395fd5e88fb10000ceaa2",
    "accountId": "563e0b6a08a2710e00057b82",
    "reservationId": "586395fd5e88fb10000cea9f",
    "amount": 0,
    "currency": "USD",
    "description": "Booking fee - Free - OZVnoAB - Luxury House Near the City - Koby",
    "isOurFee": true,
    "shouldBePaidAt": "2017-01-28T14:32:10.215Z",
    "createdAt": "2016-12-28T10:37:49.524Z",
    "__v": 0,
    "components": [],
    "paidAt": "2017-06-12T15:31:04.364Z",
    "invoiceId": "593eb3b83e1b3d040060d084"
}
Attribute Type Description
_id String Unique id
accountId String Id of the user owning this invoice.
reservationId String Id of the booking associated to this invoice item.
invoiceId String Id of the invoice this item was liked to.
createdAt Date The date this invoice was created.
amount Number The amount of this charge.
currency Enum Any supported currency.
description String Text describing the invoice item.
shouldBePaidAt Date The expected date of payment.
paidAt Date The date this invoice was paid.
isOurFee Boolean Whether it is Guesty fee.

List invoice items

{
    "count": 1,
    "limit": 10,
    "skip": 0,
    "results": [
        {
            "_id": "586395fd5e88fb10000ceaa2",
            "accountId": "563e0b6a08a2710e00057b82",
            "reservationId": "586395fd5e88fb10000cea9f",
            "amount": 0,
            "currency": "USD",
            "description": "Booking fee - Free - OZVnoAB - Luxury House Near the City - Koby",
            "isOurFee": true,
            "shouldBePaidAt": "2017-01-28T14:32:10.215Z",
            "createdAt": "2016-12-28T10:37:49.524Z",
            "__v": 0,
            "components": [],
            "paidAt": "2017-06-12T15:31:04.364Z",
            "invoiceId": "593eb3b83e1b3d040060d084"
        }
    ]
}

HTTP Request

GET /billing/invoice-items

Query Parameters

Parameter Default Description Example
methodId --- Limit results to a specific payment method 531968414930a7f09b075800
invoiceId --- Limit results to a specific invoice 531968414930a7f09b075800
include_paid true Whether to filter fo just paid items
include_unpaid true Whether to filter to just unpaid items
fields null Selection of fields, separated by space "amount"
limit 10 Pagination 10
skip 0 Pagination 0

At least one of accountId, methodId or invoiceId is required.

Response

Object of total count, pagination (limit, skip) and results as array of invoice item objects.

Retrieve an invoice item

{
    "_id": "586395fd5e88fb10000ceaa2",
    "accountId": "563e0b6a08a2710e00057b82",
    "reservationId": "586395fd5e88fb10000cea9f",
    "amount": 0,
    "currency": "USD",
    "description": "Booking fee - Free - OZVnoAB - Luxury House Near the City - Koby",
    "isOurFee": true,
    "shouldBePaidAt": "2017-01-28T14:32:10.215Z",
    "__v": 0,
    "paidAt": "2017-06-12T15:31:04.364Z",
    "invoiceId": "593eb3b83e1b3d040060d084",
    "components": [],
    "createdAt": "2016-12-28T10:37:49.524Z"
}

HTTP Request

GET /billing/invoice-items/:id

Query Parameters

Parameter Default Description Example
fields null Fields to select. If null, returns all amount currency

Download invoice's invoice items as csv

"Description","Amount","Currency","Paid at"
"Booking fee - 2.5% - GYZyAN0 - RU test - nickname - June 15th, 2017","1","USD","Jun 19th, 2017"
"Booking fee - 1.5% - gxLXmVr - Manual - Nadav  - June 12th, 2017","11","USD","Jun 12th, 2017"
"Booking fee - 1.5% - nYrV2Mp - Manual - Manhattan 1 - June 15th, 2017","2","USD","Jun 19th, 2017"
"Booking fee - 0% - MEQmRp5 - Manual - nickname - June 21st, 2017","0","USD","Jul 3rd, 2017"
"Booking fee - 1.5% - B8L7l3J - website - Luxury 123 - June 12th, 2017","1","USD","Jun 19th, 2017"
"Booking fee - 0% - KYZkn6l - Manual - nickname - June 27th, 2017","0","USD","Jun 19th, 2017"
"Booking fee - 1.5% - 8o6vQvj - elads - Liat - July 1st, 2017","2","USD","Jul 3rd, 2017"

Returns a list of all paid invoice items.

HTTP Request

POST /billing/invoice-items/download.csv

Query Parameters

Parameter Default Description Example
accountId --- Limit to user. 531968414930a7f09b075800
methodId --- Limit to payment method. 531968414930a7f09b075800
invoiceId --- What invoices to download. Can send an array. 531968414930a7f09b075800

At least one of these is required: accountId, methodId or invoiceId.

Response

CSV file with download headers. One CSV file for all items (No separate file for each invoice).

CSV is a spreadsheet of invoice items (fields): description, amount, currency, paidAt

No limit on rows count.

Billing - Payment Methods

Payment method object

{
    "_id" : "58bfe8b91e5a1c10007922c7",
    "accountId" : "57e2f67cb1261e0f0054cafe",
    "method" : "STRIPE",
    "payload" : {
        "tokenization_method" : null,
        "name" : "EXAMPLE",
        "last4" : "EXAMPLE",
        "funding" : "credit",
        "fingerprint" : "EXAMPLE",
        "exp_year" : 2016,
        "exp_month" : 6,
        "dynamic_last4" : null,
        "cvc_check" : null,
        "customer" : "cus_AFXughdfugEXAMPLE",
        "country" : "ISR",
        "brand" : "American Express",
        "address_zip_check" : null,
        "address_zip" : null,
        "address_state" : null,
        "address_line2" : null,
        "address_line1_check" : null,
        "address_line1" : null,
        "address_country" : null,
        "address_city" : null,
        "object" : "card",
        "id" : "card_19v2pAASsdaEXAMPLE"
    },
    "last4" : "EXAMPLE",
    "brand" : "American Express",
    "createdAt" : "2017-03-08T11:19:21.185Z",
    "saveForFutureUse" : true,
}
Attribute Type Description
_id String Unique id
accountId ObjectId (String) Owner
method Enum Can be any supported payment method (STRIPE, CASH etc.).
payload payload Object (see below)
saveForFutureUse Boolean
createdAt Date
last4 String
brand String Visa, MasterCard, American Express etc.

The payload object

@See Stripe api docs for description

Attribute Type
id String
object String
last4 String
brand String
funding String
exp_month Number
exp_year Number
country String
name String
address_line1 String
address_line2 String
address_city String
address_state String
address_zip String
address_country String
cvc_check String
address_line1_check String
address_zip_check String
tokenization_method String
dynamic_last4 String
metadata Object
customer String

List all payment methods

{
    "count": 1,
    "limit": 25,
    "skip": 0,
    "results": [
        {
            "_id" : "58bfe8b91e5a1c10007922c7",
            "accountId" : "57e2f67cb1261e0f0054cafe",
            "method" : "STRIPE",
            "payload" : {
                "tokenization_method" : null,
                "name" : "EXAMPLE",
                "last4" : "EXAMPLE",
                "funding" : "credit",
                "fingerprint" : "EXAMPLE",
                "exp_year" : 2016,
                "exp_month" : 6,
                "dynamic_last4" : null,
                "cvc_check" : null,
                "customer" : "cus_AFXughdfugEXAMPLE",
                "country" : "ISR",
                "brand" : "American Express",
                "address_zip_check" : null,
                "address_zip" : null,
                "address_state" : null,
                "address_line2" : null,
                "address_line1_check" : null,
                "address_line1" : null,
                "address_country" : null,
                "address_city" : null,
                "object" : "card",
                "id" : "card_19v2pAASsdaEXAMPLE"
            },
            "last4" : "EXAMPLE",
            "brand" : "American Express",
            "createdAt" : "2017-03-08T11:19:21.185Z",
            "saveForFutureUse" : true,
        }
    ]
}

HTTP Request

GET /billing/payment-methods

Query Parameters

Parameter Default Description Example
accountId null Limit to a specific user 531968414930a7f09b075800
fields null Selection of fields, separated by space "listings"

Response

Payment method objects

Add a payment method

HTTP Request

POST /billing/payment-methods

Body Parameters

Parameter Default Description Example
method null Payment method enum. stripe
listings null Array of listings ids in string format, that this payment method would be used for.
receiptExtraContent null Text that will be added to each receipt
sendReceiptsByEmail null Whether receipt should be sent out to customer.
stripe Object For payments method of type stripe.

stripe object

@See Stripe api docs for description

Parameter Default Description Example
source --- Required card token returned from Stripe.js

Response

Payment method object.

Retrieve a payment method

HTTP Request

GET /billing/payment-methods/:id

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space "listings"

Response

Payment method object.

Update a payment method

HTTP Request

PUT /billing/payment-methods/:id

Body

Parameter Default Description Example
isDefault null Whether this payment method is the default. true
listings null Strings of listing ids 531968414930a7f09b075800
receiptExtraContent null Text that will be added to each receipt Guesty, Inc.
sendReceiptsByEmail null Whether receipt should be sent out to customer. true
stripe null Update to a payment method of type stripe

stripe object

@See Stripe api docs for description

Body is applied to stripe directly.

Response

The updated payment method object.

Remove a payment method

HTTP Request

DELETE /billing/payment-methods/:id

Response

OK

Websites

The website object

{
    "_id": "59a43af221ca870f00f2a58a",
    "url": "example",
    "title": "TILTER",
    "domainName": "",
    "pic": "https://cdn.filepicker.io/api/file/gutVyCgTdmcK3uGHCsRI",
    "logo": "https://cdn.filepicker.io/api/file/A8dUZqkGRyiMdGp2xeoK",
    "maxGuests": 16,
    "color": "#6AC1FF",
    "accountId": "563e0b6a08a2710e00057b82",
    "guestyDomain": "example.guestybookings.com",
    "__v": 0,
    "companyInfo": {
        "name": "example website",
        "address": "",
        "email": "example@guesty.com",
        "phones": [
            {
                "number": "+972504048705",
                "type": "Mobile"
            }
        ]
    },
    "excludedListings": [],
    "includedListings": [
        "57e2476e58621d0f003eaac5"
    ],
    "defaultSort": "title",
    "sections": [
        {
            "index": 0,
            "name": "About",
            "type": "INFO",
            "_id": "59a43af221ca870f00f2a58d",
            "payload": {
                "description": "This is the about description",
                "title": "This is the about title"
            },
            "active": true
        },
        {
            "index": 1,
            "name": "Services",
            "type": "SERVICES",
            "payload": {
                "items": [
                    {
                        "title": "Bath is a must, otherwise you stink",
                        "description": "",
                        "icon": {
                            "name": "bath",
                            "src": "assets/images/amenities/bath.svg",
                            "cleanName": "Bath"
                        }
                    },
                    {
                        "title": "Don't BBQ after the bath!",
                        "description": "",
                        "icon": {
                            "name": "bbq",
                            "src": "assets/images/amenities/bbq.svg",
                            "cleanName": "Bbq"
                        }
                    },
                    {
                        "title": "You can always break a chair on us if you're pissed!",
                        "description": "",
                        "icon": {
                            "name": "chair",
                            "src": "assets/images/amenities/chair.svg",
                            "cleanName": "Chair"
                        }
                    }
                ],
                "description": "This is the service description",
                "title": "This is the service title"
            },
            "_id": "59a43af221ca870f00f2a58c",
            "active": true
        }
    ],
    "bookingType": "INQUIRY",
    "social": [
        {
            "url": "http://facebook.com/guesty",
            "type": "FACEBOOK",
            "_id": "59afe283fa62f80f00fdd7dd"
        }
    ],
    "defaultStatusForNewReservations": "inquiry",
    "active": true
}
Attribute Type Description
_id String Unique Id
accountId String Unique Id
active Boolean
url String
domainName String
defaultStatusForNewReservation Enum inquiry, reserved
maxGuests Number Min: 1, Max: 16
title String
pic String
logo String
color String
social [social] see below
sections [sections] see below
defaultSort Enum title, accommodates, bedrooms
GA String
includedListings [Sting]-(ObjectId) Array of the included listing Ids
excludedListings [Sting]-(ObjectId) Array of the excluded listing Ids
companyInfo [companyInfo] see below

The sections object

Attribute Type Description
active Boolean
index String Required
name String Required
type Enum SERVICE, INFO, CONTACT
payload Object

The social object

Attribute Type Description
type Enum YOUTUBE, FACEBOOK, INSTAGRAM, TWITTER
url String

The companyInfo object

Attribute Type Description
name String
address String
phones [phones]
email String

List websites

[
    {
        "_id": "59a43af221ca870f00f2a58a",
        "url": "example",
        "title": "TILTER",
        "domainName": "",
        "pic": "https://cdn.filepicker.io/api/file/gutVyCgTdmcK3uGHCsRI",
        "logo": "https://cdn.filepicker.io/api/file/A8dUZqkGRyiMdGp2xeoK",
        "maxGuests": 16,
        "color": "#6AC1FF",
        "accountId": "563e0b6a08a2710e00057b82",
        "guestyDomain": "example.guestybookings.com",
        "__v": 0,
        "companyInfo": {
            "name": "example website",
            "address": "",
            "email": "example@guesty.com",
            "phones": [
                {
                    "number": "+972504048705",
                    "type": "Mobile"
                }
            ]
        },
        "excludedListings": [],
        "includedListings": [
            "57e2476e58621d0f003eaac5"
        ],
        "defaultSort": "title",
        "sections": [],
        "bookingType": "INQUIRY",
        "social": [
            {
                "url": "http://facebook.com/guesty",
                "type": "FACEBOOK",
                "_id": "59afe283fa62f80f00fdd7dd"
            }
        ],
        "defaultStatusForNewReservations": "inquiry",
        "active": true
    }
]

HTTP Request

GET /websites/dashboard

Query Parameters

Parameter Default Description Example
fields null Selection of fields, separated by space title createdAt
sort -createdAt Field to sort by. Prepend - for DESC. createdAt
limit 25 Pagination, max: 100 25
skip 0 Pagination 0

Response

List of websites.

Retrieve a website

{
    "_id": "59a43af221ca870f00f2a58a",
    "url": "example",
    "title": "TILTER",
    "domainName": "",
    "pic": "https://cdn.filepicker.io/api/file/gutVyCgTdmcK3uGHCsRI",
    "logo": "https://cdn.filepicker.io/api/file/A8dUZqkGRyiMdGp2xeoK",
    "maxGuests": 16,
    "color": "#6AC1FF",
    "accountId": "563e0b6a08a2710e00057b82",
    "guestyDomain": "example.guestybookings.com",
    "__v": 0,
    "companyInfo": {
        "name": "example website",
        "address": "",
        "email": "example@guesty.com",
        "phones": [
            {
                "number": "+972504048705",
                "type": "Mobile"
            }
        ]
    },
    "excludedListings": [],
    "includedListings": [
        "57e2476e58621d0f003eaac5"
    ],
    "defaultSort": "title",
    "sections": [],
    "bookingType": "INQUIRY",
    "social": [
        {
            "url": "http://facebook.com/guesty",
            "type": "FACEBOOK",
            "_id": "59afe283fa62f80f00fdd7dd"
        }
    ],
    "defaultStatusForNewReservations": "inquiry",
    "active": true
}

HTTP Request

GET /websites/dashboard/:id

Query Parameters

Parameter Default Description Example
limit 10 Pagination for invoice items 10
skip 0 Pagination for invoice items 0

Response

The requested website object

Delete a website

"OK"

HTTP Request

DELETE /websites/dashboard/:id

Response

OK

WebHooks

The Webhooks object

Attribute Type Description
_id String (Unique)
url String
accountId String (Unique)
events [Enum] (See Guesty events)

Guesty events

List all account WebHooks

HTTP Request

GET /webhooks

Authorization

Requires

Response

An Array of WebHooks

[
    {
        "_id": "595a7fc636f2491000b6b81a",
        "accountId": "55b9f9b5393dfe0e004b6c5d",
        "url": "https://www.hookurl.com",
        "__v": 0,
        "events": [
            "guest.updated",
            "listing.new",
            "listing.removed",
            "payments.failed",
            "reservation.new",
            "reservation.updated",
            "reservation.reviewed",
            "task.created",
            "task.updated"
        ]
    }
]

Create a WebHook

HTTP Request

POST /webhooks

Body

Parameter Default
url Required
accountId Required
events Required

Response

Status code of 201 created. Created WebHook Object, see List all account WebHooks

Retrieve a WebHook

HTTP Request

GET /webhooks/:id

Response

An WebHook Object, see List all account WebHooks

Update a WebHook

HTTP Request

PUT /webhooks/:id

Body

see Create a WebHooks

Response

Status code 204 if success

Delete a WebHook

HTTP Request

DELETE /webhooks/:id

Response

Status code 204 if success

Webhook Structure

guest.created

{
    "guest" : {
        "__v" : 0,
        "fullName" : "Example Guest",
        "firstName" : "Example",
        "lastName" : "Guest",
        "email" : "example@email.com",
        "accountId" : "563e0b6a08a2710e00057b82",
        "_id" : "59ccd0620de3881000b0f2e1",
        "paymentMethodIds" : [],
        "communicationMethods" : [
            "email"
        ],
        "airbnb" : {
            "id" : 1506594914760
        },
        "phones" : [],
        "emails" : [
            "example@email.com"
        ],
        "pictures" : [],
        "verifications" : []
    },
    "by" : "Someone from my team",
    "event" : "guest.created"
}

Body

Attribute Type Description
guest Object guest object - see The guest object
by String
event String guest.created

guest.deleted

{
    "guest":{
        "_id" : "59ccd0620de3881000b0f2e1",
        "fullName":"Example Guest",
        "firstName":"Example",
        "lastName":"Guest",
        "email":"example@email.com",
        "accountId":"563e0b6a08a2710e00057b82",
        "__v":0,