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 | |
| 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 failedmissing if missing payment methodfailed 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' |
| 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 /usersResponse
{
"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' |
| 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 |
|---|---|---|
| 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
Retrieve a listing paymentProviderId
HTTP Request
GET /:id?fields=paymentProviderId
{ "paymentProviderId": "5f79927568c585002cc14f24",
"paymentProvider": {
"_id": "5f79927568c585002cc14f24",
"status": "ACTIVE",
"syncedAt": "2019-11-20T21:31:01.109Z",
"lastPendingPaymentDate": "2021-02-09T16:12:56.536Z",
"pendingPaymentsCount": 7,
"paymentMethodsCount": 273,
"providerAccountId": "acct_19nmQxLYcJ0oiNhY",
"isDefault": false,
"providerType": "stripe",
"connectedBy": "MSA migration",
"accountName": "Guesty Inc.",
"defaultCurrency": "usd",
"statsLastUpdated": "2021-03-14T14:08:06.539Z"
}
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,
"pt": false
},
"minNights": 7,
"price": 10000,
"allotment": 0,
"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 |
| allotment | Number | Number of available rooms in the listing |
Retrieving a 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,
"pt": 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,
"pt": 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,
"pt": 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,
"pt": 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,
"pt": false
},
"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
[pt] => Preparation Time
[an] => Advance Notice
Response
Array of calendar day objects
Retrieving 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,
"pt": 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,
"pt": 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,
"pt": 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,
"pt": 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,
"pt": 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,
"pt": 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
Calendar
Note: This new API is available at the base endpoint:
https://api.guesty.com/api/v2/availability-pricing/api
Example:
GET https://api.guesty.com/api/v2/availability-pricing/api/calendar/listings/5e2f1a94b189e6008fcd8293
The Calendar day object
{
"date": "2021-01-01",
"listingId": "5988346d3c31bf0f00747eb6",
"currency": "EUR",
"price": 50,
"isBasePrice": true,
"minNights": 2,
"isBaseMinNights": true,
"status": "booked",
"allotment": 0,
"blocks": {
"m": false,
"r": false,
"b": true,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false,
"pt": false
},
"blockRefs": [
{
"_id": "5fe9c819a141ab0026c901c7",
"reservation": {
"listing": {
"timezone": "Asia/Jerusalem",
"defaultCheckInTime": "15:00"
},
"money": {
"currency": "EUR",
"hostPayout": 367.55,
"totalPaid": 0,
"balanceDue": 367.55
},
"guest": {
"_id": "5fe9c81834209c002c8ecd80"
},
"integration": {
"platform": "manual"
},
"_id": "5fe9c81934209c002c8ecd8b",
"status": "confirmed",
"checkIn": "2020-12-30T13:00:00.000Z",
"checkOut": "2021-01-02T08:00:00.000Z",
"nightsCount": 3,
"guestsCount": 2,
"listingId": "5988346d3c31bf0f00747eb6",
"checkInDateLocalized": "2020-12-30",
"checkOutDateLocalized": "2021-01-02",
"accountId": "596f6fe706112710005d96ff",
"guestId": "5fe9c81834209c002c8ecd80",
"source": "Manual",
"confirmationCode": "J86mAAAM2"
},
"listingId": "5988346d3c31bf0f00747eb6",
"startDate": "2020-12-30T00:00:00.000Z",
"endDate": "2021-01-01T00:00:00.000Z",
"type": "b",
"reservationId": "5fe9c81934209c002c8ecd8b"
}
],
"reservationId": "5fe9c81934209c002c8ecd8b",
"reservation": {
"listing": {
"timezone": "Asia/Jerusalem",
"defaultCheckInTime": "15:00"
},
"money": {
"currency": "EUR",
"hostPayout": 367.55,
"totalPaid": 0,
"balanceDue": 367.55
},
"guest": {
"_id": "5fe9c81834209c002c8ecd80"
},
"integration": {
"platform": "manual"
},
"_id": "5fe9c81934209c002c8ecd8b",
"status": "confirmed",
"checkIn": "2020-12-30T13:00:00.000Z",
"checkOut": "2021-01-02T08:00:00.000Z",
"nightsCount": 3,
"guestsCount": 2,
"listingId": "5988346d3c31bf0f00747eb6",
"checkInDateLocalized": "2020-12-30",
"checkOutDateLocalized": "2021-01-02",
"accountId": "596f6fe706112710005d96ff",
"guestId": "5fe9c81834209c002c8ecd80",
"source": "Manual",
"confirmationCode": "J86mAAAM2"
},
"cta": false,
"ctd": false
}
| Attribute | Type | Description |
|---|---|---|
| date | String (Date) | Format: YYYY-MM-DD |
| listingId | String (ObjectId) | ref to Listing |
| currency | String (Enum) | 3 letter iso currency code |
| price | Number | The price that that day cost |
| isBasePrice | Boolean | Whether this is the listing's base price, or was specifically set for this day |
| minNights | Number | The minimum reservation nights if reservation check in is on this day |
| isBaseMinNights | Boolean | Whether this is the listing's minimum nights, or was specifically set for this day |
| status | String (Enum) | available, unavailable, reserved, booked |
| allotment | Number | Number of available rooms in the listing |
| cta | Boolean | Closed To Arrival - Whether reservations are prevented from being booked starting on this day |
| ctd | Boolean | Closed To Departure - Whether reservations are allowed to be booked ending on this day |
| note | String | Description of why this day is blocked |
| reservationId | String (ObjectId) | ID of linked reservation (Only if booked or reserved) |
| reservation | Object | Linked reservation (Only if booked or reserved) |
| blocks | Object | (backwards-compatible) A map of flags indicating why this day is not available. See below for more details |
| blockRefs | Array | A list of blocks relevant to this day |
| rulesApplied | Array | A list of revenue-management rules that were actively applied to the pricing for this day |
The block object
{
"_id": "5fe9c819a141ab0026c901c7",
"listingId": "5988346d3c31bf0f00747eb6",
"startDate": "2020-12-30T00:00:00.000Z",
"endDate": "2021-01-01T00:00:00.000Z",
"type": "m"
}
This denotes a 2-day long manual block on listing 5988346d3c31bf0f00747eb6 starting on 2020-12-30 and ending on 2020-01-01
Reservation-related blocks (b, r, sr, pt, o ) will have additional reservation data attached to the block.
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
[pt] => Preparation Time
[an] => Advance Notice
Retrieve single calendar
{
"status": 200,
"data": {
"days": [
{
"date": "2021-01-01",
"listingId": "5988346d3c31bf0f00747eb6",
"currency": "EUR",
"price": 50,
"isBasePrice": true,
"minNights": 2,
"isBaseMinNights": true,
"status": "booked",
"blocks": {
"m": false,
"r": false,
"b": true,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false,
"pt": false
},
"blockRefs": [
{
"_id": "5fe9c819a141ab0026c901c7",
"reservation": {
"listing": {
"timezone": "Asia/Jerusalem",
"defaultCheckInTime": "15:00"
},
"money": {
"currency": "EUR",
"hostPayout": 367.55,
"totalPaid": 0,
"balanceDue": 367.55
},
"guest": {
"_id": "5fe9c81834209c002c8ecd80"
},
"integration": {
"platform": "manual"
},
"_id": "5fe9c81934209c002c8ecd8b",
"status": "confirmed",
"checkIn": "2020-12-30T13:00:00.000Z",
"checkOut": "2021-01-02T08:00:00.000Z",
"nightsCount": 3,
"guestsCount": 2,
"listingId": "5988346d3c31bf0f00747eb6",
"checkInDateLocalized": "2020-12-30",
"checkOutDateLocalized": "2021-01-02",
"accountId": "596f6fe706112710005d96ff",
"guestId": "5fe9c81834209c002c8ecd80",
"source": "Manual",
"confirmationCode": "J86mAAAM2"
},
"listingId": "5988346d3c31bf0f00747eb6",
"startDate": "2020-12-30T00:00:00.000Z",
"endDate": "2021-01-01T00:00:00.000Z",
"type": "b",
"reservationId": "5fe9c81934209c002c8ecd8b"
}
],
"reservationId": "5fe9c81934209c002c8ecd8b",
"reservation": {
"listing": {
"timezone": "Asia/Jerusalem",
"defaultCheckInTime": "15:00"
},
"money": {
"currency": "EUR",
"hostPayout": 367.55,
"totalPaid": 0,
"balanceDue": 367.55
},
"guest": {
"_id": "5fe9c81834209c002c8ecd80"
},
"integration": {
"platform": "manual"
},
"_id": "5fe9c81934209c002c8ecd8b",
"status": "confirmed",
"checkIn": "2020-12-30T13:00:00.000Z",
"checkOut": "2021-01-02T08:00:00.000Z",
"nightsCount": 3,
"guestsCount": 2,
"listingId": "5988346d3c31bf0f00747eb6",
"checkInDateLocalized": "2020-12-30",
"checkOutDateLocalized": "2021-01-02",
"accountId": "596f6fe706112710005d96ff",
"guestId": "5fe9c81834209c002c8ecd80",
"source": "Manual",
"confirmationCode": "J86mAAAM2"
},
"cta": false,
"ctd": false
},
{
"date": "2021-01-02",
"listingId": "5988346d3c31bf0f00747eb6",
"currency": "EUR",
"price": 50,
"isBasePrice": true,
"minNights": 2,
"isBaseMinNights": true,
"status": "available",
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false,
"pt": false
},
"blockRefs": [],
"cta": false,
"ctd": false
}
]
},
"message": "OK"
}
HTTP Request
GET availability-pricing/api/calendar/listings/:listingId
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| startDate | Required | Return dates starting from this date. Format: YYYY-MM-DD. |
2016-01-10 |
| endDate | Required | Return dates ending at this date. Format: YYYY-MM-DD. |
2016-01-11 |
| includeAllotment | Optional | Return day objects including allotment | true |
Response
Array of calendar day objects
{
"status": 200,
"data": {
"days": [
{
"date": "2021-01-01",
"listingId": "5988346d3c31bf0f00747eb6",
"currency": "EUR",
"price": 50,
"isBasePrice": true,
"minNights": 2,
"isBaseMinNights": true,
"status": "booked",
"blocks": {
"m": false,
"r": false,
"b": true,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false,
"pt": false
},
"blockRefs": [
{
"_id": "5fe9c819a141ab0026c901c7",
"reservation": {
"listing": {
"timezone": "Asia/Jerusalem",
"defaultCheckInTime": "15:00"
},
"money": {
"currency": "EUR",
"hostPayout": 367.55,
"totalPaid": 0,
"balanceDue": 367.55
},
"guest": {
"_id": "5fe9c81834209c002c8ecd80"
},
"integration": {
"platform": "manual"
},
"_id": "5fe9c81934209c002c8ecd8b",
"status": "confirmed",
"checkIn": "2020-12-30T13:00:00.000Z",
"checkOut": "2021-01-02T08:00:00.000Z",
"nightsCount": 3,
"guestsCount": 2,
"listingId": "5988346d3c31bf0f00747eb6",
"checkInDateLocalized": "2020-12-30",
"checkOutDateLocalized": "2021-01-02",
"accountId": "596f6fe706112710005d96ff",
"guestId": "5fe9c81834209c002c8ecd80",
"source": "Manual",
"confirmationCode": "J86mAAAM2"
},
"listingId": "5988346d3c31bf0f00747eb6",
"startDate": "2020-12-30T00:00:00.000Z",
"endDate": "2021-01-01T00:00:00.000Z",
"type": "b",
"reservationId": "5fe9c81934209c002c8ecd8b"
}
],
"reservationId": "5fe9c81934209c002c8ecd8b",
"reservation": {
"listing": {
"timezone": "Asia/Jerusalem",
"defaultCheckInTime": "15:00"
},
"money": {
"currency": "EUR",
"hostPayout": 367.55,
"totalPaid": 0,
"balanceDue": 367.55
},
"guest": {
"_id": "5fe9c81834209c002c8ecd80"
},
"integration": {
"platform": "manual"
},
"_id": "5fe9c81934209c002c8ecd8b",
"status": "confirmed",
"checkIn": "2020-12-30T13:00:00.000Z",
"checkOut": "2021-01-02T08:00:00.000Z",
"nightsCount": 3,
"guestsCount": 2,
"listingId": "5988346d3c31bf0f00747eb6",
"checkInDateLocalized": "2020-12-30",
"checkOutDateLocalized": "2021-01-02",
"accountId": "596f6fe706112710005d96ff",
"guestId": "5fe9c81834209c002c8ecd80",
"source": "Manual",
"confirmationCode": "J86mAAAM2"
},
"cta": false,
"ctd": false
},
{
"date": "2021-01-02",
"listingId": "5988346d3c31bf0f00747eb6",
"currency": "EUR",
"price": 50,
"isBasePrice": true,
"minNights": 2,
"isBaseMinNights": true,
"status": "available",
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false,
"pt": false
},
"blockRefs": [],
"cta": false,
"ctd": false
}
]
},
"message": "OK"
}
Retrieve multiple calendars
{
"status": 200,
"data": {
"days": [
{
"date": "2021-01-02",
"listingId": "5988346d3c31bf0f00747eb6",
"currency": "EUR",
"price": 50,
"isBasePrice": true,
"minNights": 2,
"isBaseMinNights": true,
"status": "available",
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false,
"pt": false
},
"blockRefs": [],
"cta": false,
"ctd": false
},
{
"date": "2021-01-03",
"listingId": "5988346d3c31bf0f00747eb6",
"currency": "EUR",
"price": 50,
"isBasePrice": true,
"minNights": 2,
"isBaseMinNights": true,
"status": "available",
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false,
"pt": false
},
"blockRefs": [],
"cta": false,
"ctd": false
},
{
"date": "2021-01-02",
"listingId": "5a5370ea3197a81500908a69",
"currency": "USD",
"price": 360,
"isBasePrice": true,
"minNights": 1,
"isBaseMinNights": true,
"status": "available",
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false,
"pt": false
},
"blockRefs": [],
"cta": false,
"ctd": false
},
{
"date": "2021-01-03",
"listingId": "5a5370ea3197a81500908a69",
"currency": "USD",
"price": 360,
"isBasePrice": true,
"minNights": 1,
"isBaseMinNights": true,
"status": "available",
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false,
"pt": false
},
"blockRefs": [],
"cta": false,
"ctd": false
}
]
},
"message": "OK"
}
HTTP Request
GET availability-pricing/api/calendar/listings
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| startDate | Required | Return dates starting from this date. Format: YYYY-MM-DD. |
2016-01-10 |
| endDate | Required | Return dates ending at this date. Format: YYYY-MM-DD. |
2016-01-11 |
| listingIds | Required | Array or comma-separated string of listing ids whose calendars you want to retrieve | |
| includeAllotment | Optional | Return day objects including allotment | true |
Example Call
https://api.guesty.com/api/v2/availability-pricing/api/calendar/listings?startDate=2021-01-02&endDate=2021-01-03&listingIds=5988346d3c31bf0f00747eb6,5a5370ea3197a81500908a69
Response
Array of calendar days, in the same format as the single calendar response.
Update single calendars
{
"startDate": "2021-01-01",
"endDate": "2021-01-02",
"price": 200,
"minNights": 5,
"status": "available"
}
HTTP Request
PUT availability-pricing/api/calendar/listings/:listingId
Body Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| startDate | Required | Update dates starting from this date. Format: yyyy-mm-dd. |
"2016-01-10" |
| endDate | 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 |
| isBasePrice | Boolean | Whether to reset prices for the range to the listing's base price | |
| minNights | Number | New min nights value" | '2' |
| isBaseMinNights | Boolean | Whether to reset min nights for the range to the listing's base min nights | |
| note | --- | Note to add to those dates. | |
| cta | Boolean | Set Closed To Arrival for the date range. | |
| ctd | Boolean | Set Closed To Departure for the date range. |
Response
OK
Update multiple calendars
[
{
"listingId": "5a5370ea3197a81500908a69",
"startDate": "2021-01-01",
"endDate": "2021-01-31",
"price": 200,
"minNights": 5,
"status": "available"
},
{
"listingId": "5a5370ea3197a81500908a69",
"startDate": "2021-02-01",
"endDate": "2021-02-20",
"status": "unavailable",
"note": "Closed for repairs"
},
]
HTTP Request
PUT availability-pricing/api/calendar/listings
Body Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| listingId | Required | Update this listingId | |
| startDate | Required | Update dates starting from this date. Format: yyyy-mm-dd. |
"2016-01-10" |
| endDate | 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 |
| isBasePrice | Boolean | Whether to reset prices for the range to the listing's base price | |
| minNights | Number | New min nights value" | '2' |
| isBaseMinNights | Boolean | Whether to reset min nights for the range to the listing's base min nights | |
| note | --- | Note to add to those dates. | |
| cta | Boolean | Set Closed To Arrival for the date range. | |
| ctd | Boolean | Set Closed To Departure for the date range. |
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 | |
| ---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.
Refund an existing payment
HTTP Request
POST /reservations/:id/payments/:paymentId/refund
| Parameter | Default | Description |
|---|---|---|
| paymentId | Required | the _id of the payment to refund |
Body
| Parameter | Default | Description |
|---|---|---|
| amount | Required | amount to be refund. Must be less or equal to amount - total refund for the payment |
Example
Body
{"amount": 10}
Response
Retrieve the updated reservation, selection of money.payments field.
Cancel an existing payment
HTTP Request
PUT /reservations/:id/payments/:paymentId
| Parameter | Default | Description |
|---|---|---|
| paymentId | Required | the _id of the payment to cancel |
Body
| Parameter | Default | Description |
|---|---|---|
| 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}}
Reservation Guest no-show report
HTTP Request
POST /reservations/{reservation_id}/reports/guestNoShow
Validations
- Report available only for bookingcom reservations: system will check
reservation.integration.platform===bookingCom. - Channel validation restrictions also applied to reservation you want to report.
{
"isWaiveFee": false
}
Body
| Parameter | Default | Description |
|---|---|---|
| isWaiveFee | Required | bool specifies whether the property will waive the no-show fees. |
Reservation Guest misconduct report
HTTP Request
POST /reservations/{reservation_id}/reports/guestMisconduct
Validations
- Report available only for bookingcom reservations: system will check
reservation.integration.platform===bookingCom. - Channel validation restrictions also applied to reservation you want to report.
- Should meet category from the list below
| Category ID | Description |
|---|---|
| 0 | Abusive behaviour |
| 1 | Payment issue |
| 2 | Left property dirty |
| 5 | Illegal activities |
| 7 | Breaking house rules |
| 9 | Property damage |
Body
| Parameter | Default | Description |
|---|---|---|
| categoryId | Required | number category id of misconduct issue |
| detailsText | Required | string up to 254 characters |
| escalateReport | false | bool a flag that indicates whether you would like Booking.com to follow up on this incident |
| rebookingAllowed | true | bool a flag that indicates whether you would like Booking.com to follow up on this incident |
| damageCost | number amount in Guesty listing currency |
{
"categoryId": "5",
"detailsText": "Just testing the API",
"escalateReport": true,
"damageCost": 20
}
Reservation alteration request
Send a request modification request to external channel to modify reservation.
Supported channels: bookingCom
Validations
- Report available only for bookingcom reservations: system will check
reservation.integration.platform===bookingCom. - Channel validation restrictions also applied to reservation you want to report.
- reservation status is
confirmed
HTTP Request
POST /reservations/{reservation_id}/reports/stayChangeRequest
Body
| Parameter | Default | Description |
|---|---|---|
| checkIn | Required | new reservation check-in date |
| checkOut | Required | new reservation check-out date |
| price | Required | reservation total price in listing currency after modification |
{
"checkIn": "2021-01-07",
"checkOut": "2021-01-11",
"price": 50
}
Validations
- Report available only for bookingcom reservations: system will check
reservation.integration.platform===bookingCom. - Channel validation restrictions also applied to reservation you want to report.
Reservations V2
Base URL
Please note that the base URL from this is different from the rest of the routes in this document.
https://api.guesty.com/api/reservations-api/reservations
Pre-Approve a reservation
Response
{
"_id": "59b9414932123a1000b7cd55",
"checkIn": "2017-09-15T12:00:00.000Z",
"checkOut": "2017-09-18T08:00:00.000Z",
"checkInDateLocalized": "2017-09-15",
"checkOutDateLocalized": "2017-09-18",
"listingId": "59b928bb8e6bb31000219e58",
"integration": {
"_id": "5784a3cc64ce9c0e00ecaf1e",
"platform": "airbnb2",
},
"status": "inquiry",
"accountId": "563e0b6a08a2710e00057b82",
"guestId": "59b9414932123a1000b7cd54",
"guestsCount": 1,
"source": "Airbnb",
"guest": {
"fullName": "Eli Moscowitch",
"phone": 50394834752,
"email": "Placeholder@placeholder.com"
},
"preApproveState": true
}
HTTP Request
POST /:reservationId/pre-approve
Response
Reservation object
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 | |
| 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
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
Update owner reservation
HTTP Request
PUT /owners-reservations/:id
Validations
- System will make sure reservation is according to terms (checkIn, checkOut), and decline otherwise (500).
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 | |
| 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 | |
| Required | ||
| listings | Required | |
| ownersPortalSettings | Optional | |
| locale | Optional | |
| active | Optional | |
| allowReservations | Optional | |
| showReservationTooltips | Optional | |
| workingCapital | Optional | |
| accountId | Optional | |
| firstName | Optional | |
| lastName | Optional | |
| 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 | |
| Required | ||
| listings | Required | |
| ownersPortalSettings | Optional | |
| locale | Optional | |
| active | Optional | |
| allowReservations | Optional | |
| showReservationTooltips | Optional | |
| workingCapital | Optional | |
| accountId | Optional | |
| firstName | Optional | |
| lastName | Optional | |
| 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 |
| 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 |
| paymentProviderId | null |
id of payment provider used to create stripeCardToken. Default payment provider will be used if not defined |
example
{"stripeCardToken": "pm_...", "skipSetupIntent": false, "paymentProviderId": "5fe4b21675087f01a3c5ab5b" }
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 | |
| 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 | ||
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) |
| 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 |
| 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) |
| 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) |
| 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 |
| 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 | |
| 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
- First request will require only limit parameter and in response you will get cursor object.
"cursor": {
"after": "MjAyMC0wNy0wOVQxMDowMzozOS43ODBaXzVmMDZlYjdiYzVkODk4MDAyYWMwNTM2Nw==",
"before": "jAyMC0wNy0xMFQxMDoyMToxMy4yODNaXzVmMDg0MTE5MjhlZjlmMDAyODJjMTVhYg==",
}
- Use cursor.after to send in query params cursorAfter parameter in order to move forward.
- Use cursor.before to send in query params cursorBefore parameter in order to move backwards.
- An empty string in after or before cursor in response will indicate that there is no more documents in this direction.
- If you sort buy something different than
createdAt, please make sure include this parameter in fields, or you will get empty cursor. cursorAfterandcursorBeforeare not allowed to be used at the same time in one request.
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"