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
Update a listing
HTTP Request
PUT /listings/:id
Response
Retrieve the updated listing, selection of fields that were sent in body.
Availability settings
HTTP Request
PUT /listings/:id/availability-settings
Body
| Parameter | Default | Description | Example |
|---|---|---|---|
| calendarRules | Requiered | Main Object | ------- |
| defaultAvailability | ------- | The default availability of the listing | AVAILABLE/BLOCKED |
| advanceNotice | ------- | ------- | Please see advanceNotice object |
| rentalPeriods | ------- | ------- | Please see rentalPeriods object |
| bookingWindow | ------- | ------- | Please see bookingWindow object |
Response
The updated object.
Add new integration for a listing
{
"_id": "59b928bb8e6bb31000219e58",
"integrations": [
{
"platform": "rentalsUnited",
"_id": "596b6f5aa6bd32100050be2a"
},
{
"platform": "airbnb",
"_id": "563e0b6a08a2710e00057b83"
}
],
"id": "59b928bb8e6bb31000219e58"
}
HTTP Request
POST /listings/:id/integrations
Body
| Parameter | Default | Description |
|---|---|---|
| _id | Required | id of the integration to add |
Example
Body
{"_id":"563e0b6a08a2710e00057b83"}
Response
Retrieve the updated listing, with the selection of only integrations field.
List all cities
[
"Burnt Ranch",
"New York",
"Autun",
"Kfar Sirkin",
"London",
"Newton",
"Atlanta",
"Montpelier",
"Tel Aviv-Yafo",
"Decatur",
"Vancouver",
"Amsterdam",
"Cuyahoga Falls",
"Palo Alto",
"Ramat Gan"
]
HTTP Request
GET /listings/cities
Response
Array of cities (strings).
List all tags
[
"Tag A",
"Tag B",
"Tag C"
]
HTTP Request
GET /listings/tags
Response
Array of tags (strings).
Export as CSV
HTTP Request
POST /listings.csv
Same as GET /listings but results are returned as a downloadable csv file
Send results in email
HTTP Request
POST /listings.email
Same as /listings but results are sent as an email
Body Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| to | Required | Address of recipient | koby@guesty.com |
Get all custom fields- Listings
HTTP Request
GET /listings/:Id/custom-fields/
Get custom field-Listings
HTTP Request
GET /listings/:Id/custom-fields/{field_id}
Update Listing's Custom Fields
HTTP Request
PUT /listings/:Id/custom-fields
Body
{
"customFields": [
{
"fieldId": "{{fieldId}}",
"value": "{{value}}"
}
]
}
| Parameter | Default | Description | Example |
|---|---|---|---|
| fieldId | ------- | the field id | "5f744b491af840002ca636a2" |
| value | ------- | The text field name | Door code |
Response
The updated object.
Delete Listing's Custom Fields
HTTP Request
DELETE /listings/{listing_id}/custom-fields/{field_id}
Listing's calendar
The Calendar day object
{
"_id": "5e2f1a9d6d808d0022e63c60",
"date": "2020-05-05",
"listingId": "5e2f1a94b189e6008fcd8293",
"status": "unavailable",
"priceUsd": 1654,
"accountId": "563e0b6a08a2710e00057b82",
"lastSyncedAt": "2020-01-28T06:55:09.301Z",
"note": "",
"currency": "CAD",
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": true,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false,
"an": true
},
"minNights": 7,
"price": 10000,
"notDefaultAvailability": true,
"isBasePrice": true,
"listing": {
"_id": "5e2f1a94b189e6008fcd8293",
"prices": {
"currency": "CAD"
}
| Attribute | Type | Description |
|---|---|---|
| date | String (Date) | Format: YYYY-MM-DD |
| accountId | String (ObjectId) | ref to Account |
| listingId | String (ObjectId) | ref to Listing |
| status | String (Enum) | available, unavailable, reserved, booked |
| note | String | |
| price | Number | The price that that day cost |
| minNights | Number | The minimum reservation nights if reservation check in is on this day |
| currency | String (Enum) | 3 letter iso currency code |
| reservationId | String (ObjectId) | Linked reservation (Only if booked or reserved) |
| originalPrice | Number | Used by pricing automation |
| ignoreAutoPricing | Boolean | Ignore this day in pricing automation |
Retrieve single calendar
[
{
"_id": "5e2f1aa0704789001e544e67",
"date": "2020-05-01",
"listingId": "5e2f1a94b189e6008fcd8293",
"status": "unavailable",
"priceUsd": 1654,
"accountId": "563e0b6a08a2710e00057b82",
"lastSyncedAt": "2020-01-28T06:55:09.290Z",
"note": "",
"currency": "CAD",
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": true,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false
},
"minNights": 7,
"price": 10000,
"notDefaultAvailability": true,
"isBasePrice": true,
"listing": {
"_id": "5e2f1a94b189e6008fcd8293",
"prices": {
"currency": "CAD"
}
}
},
{
"_id": "5e2f1a9e1593430022ab816d",
"date": "2020-05-02",
"listingId": "5e2f1a94b189e6008fcd8293",
"status": "unavailable",
"priceUsd": 1654,
"accountId": "563e0b6a08a2710e00057b82",
"lastSyncedAt": "2020-01-28T06:55:09.293Z",
"note": "",
"currency": "CAD",
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": true,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false
},
"minNights": 7,
"price": 10000,
"notDefaultAvailability": true,
"isBasePrice": true,
"listing": {
"_id": "5e2f1a94b189e6008fcd8293",
"prices": {
"currency": "CAD"
}
}
},
{
"_id": "5e2f1a9f39b941001ed68f10",
"date": "2020-05-03",
"listingId": "5e2f1a94b189e6008fcd8293",
"status": "unavailable",
"priceUsd": 1654,
"accountId": "563e0b6a08a2710e00057b82",
"lastSyncedAt": "2020-01-28T06:55:09.295Z",
"note": "",
"currency": "CAD",
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": true,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false
},
"minNights": 7,
"price": 10000,
"notDefaultAvailability": true,
"isBasePrice": true,
"listing": {
"_id": "5e2f1a94b189e6008fcd8293",
"prices": {
"currency": "CAD"
}
}
},
{
"_id": "5e2f1aa1e04b8800237ab257",
"date": "2020-05-04",
"listingId": "5e2f1a94b189e6008fcd8293",
"status": "unavailable",
"priceUsd": 1654,
"accountId": "563e0b6a08a2710e00057b82",
"lastSyncedAt": "2020-01-28T06:55:09.297Z",
"note": "",
"currency": "CAD",
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": true,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false
},
"minNights": 7,
"price": 10000,
"notDefaultAvailability": true,
"isBasePrice": true,
"listing": {
"_id": "5e2f1a94b189e6008fcd8293",
"prices": {
"currency": "CAD"
}
}
},
{
"_id": "5e2f1a9d6d808d0022e63c60",
"date": "2020-05-05",
"listingId": "5e2f1a94b189e6008fcd8293",
"status": "unavailable",
"priceUsd": 1654,
"accountId": "563e0b6a08a2710e00057b82",
"lastSyncedAt": "2020-01-28T06:55:09.301Z",
"note": "",
"currency": "CAD",
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": true,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false,
"an": true
},
"minNights": 7,
"price": 10000,
"notDefaultAvailability": true,
"isBasePrice": true,
"listing": {
"_id": "5e2f1a94b189e6008fcd8293",
"prices": {
"currency": "CAD"
}
}
}
]
HTTP Request
GET /listings/:id/calendar
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| from | Required | Return dates starting from this date. Format: YYYY-MM-DD. |
2016-01-10 |
| to | Required | Return dates ending at this date. Format: YYYY-MM-DD. |
2016-01-11 |
| minNights | false | if true, returns the min night value of each day | true |
| fields | null |
Selection of fields, separated by space | status |
The Block Types
[m] => Manual
[r] => Reserved
[b] => Booked
[bd] => By Default
[sr] => Smart Rules
[abl] => Annual Booking Limit
[a] => Allotment
[bw] => Booking Window
[o] => Owners
Response
Array of calendar day objects
Retrieve multiple calendars
[
{
"listingId": "5d64d06ea92d50005b04611c",
"date": "2020-05-05",
"status": "available",
"price": 1,
"isBasePrice": true,
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false
},
"rulesApplied": [
{
"rule": "repeated days (tuesday)",
"adjustmentPercentage": -30
},
{
"rule": "minAdjustmentPercentage",
"adjustmentPercentage": -20
}
],
"listing": {
"_id": "5d64d06ea92d50005b04611c",
"prices": {}
}
},
{
"listingId": "5d64d06ea92d50005b04611c",
"date": "2020-05-06",
"status": "available",
"price": 1,
"isBasePrice": true,
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false
},
"rulesApplied": [
{
"rule": "repeated days (wednesday)",
"adjustmentPercentage": -30
},
{
"rule": "minAdjustmentPercentage",
"adjustmentPercentage": -20
}
],
"listing": {
"_id": "5d64d06ea92d50005b04611c",
"prices": {}
}
},
{
"listingId": "5d64d06ea92d50005b04611c",
"date": "2020-05-07",
"status": "available",
"price": 1,
"isBasePrice": true,
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false
},
"rulesApplied": [
{
"rule": "repeated days (thursday)",
"adjustmentPercentage": -30
},
{
"rule": "minAdjustmentPercentage",
"adjustmentPercentage": -20
}
],
"listing": {
"_id": "5d64d06ea92d50005b04611c",
"prices": {}
}
},
{
"listingId": "5d64d06ea92d50005b04611c",
"date": "2020-05-08",
"status": "available",
"price": 1,
"isBasePrice": true,
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false
},
"rulesApplied": [
{
"rule": "repeated days (friday)",
"adjustmentPercentage": 30
},
{
"rule": "maxAdjustmentPercentage",
"adjustmentPercentage": 20
}
],
"listing": {
"_id": "5d64d06ea92d50005b04611c",
"prices": {}
}
},
{
"listingId": "5d64d06ea92d50005b04611c",
"date": "2020-05-09",
"status": "available",
"price": 1,
"isBasePrice": true,
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false
},
"rulesApplied": [
{
"rule": "repeated days (saturday)",
"adjustmentPercentage": 40
},
{
"rule": "maxAdjustmentPercentage",
"adjustmentPercentage": 20
}
],
"listing": {
"_id": "5d64d06ea92d50005b04611c",
"prices": {}
}
},
{
"listingId": "5d64d06ea92d50005b04611c",
"date": "2020-05-10",
"status": "available",
"price": 1,
"isBasePrice": true,
"blocks": {
"m": false,
"r": false,
"b": false,
"bd": false,
"sr": false,
"abl": false,
"a": false,
"bw": false,
"o": false
},
"rulesApplied": [
{
"rule": "repeated days (sunday)",
"adjustmentPercentage": 40
},
{
"rule": "maxAdjustmentPercentage",
"adjustmentPercentage": 20
}
],
"listing": {
"_id": "5d64d06ea92d50005b04611c",
"prices": {}
}
}
]
HTTP Request
GET /listings/calendars
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| ids | first 10 listings | Array of listing ids to return, maximum of 15 listings. | ids=5dc1aee9a022cb002029a5c2,ids=5dc1aef496be0d001f388fa7 |
| from | Required | Return dates starting from this date. Format: yyyy-mm-dd. |
2016-01-10 |
| to | Required | Return dates ending at this date. Format: yyyy-mm-dd. |
2016-01-11 |
| minNights | false | if true, returns the min night value of each day | true |
| fields | null |
Selection of fields, separated by space. use minNights to return the min nights per day | status minNights |
Example Call
https://api.guesty.com/api/v2/listings/calendars?ids=5dc1aee9a022cb002029a5c2&ids=5dc1aef496be0d001f388fa7&ids=5de0599ad373bc001e0e0c11&ids=5defc258eaed8f001fda8caf&ids=5df1b0b1bd3702001e9fbb3c&ids=5df1bd01685c34001f3c8049&ids=5e16853755624f001f018e6b&ids=5dfc18e1df04d9001f7a4426&ids=5ddfee774d488f001ee48227&ids=5e18d2055cc00c0021a0e7d0&ids=5de084f33bdf86001efc1039&ids=5df86d70c762b3002372bdae&ids=5e0cc60e2ff5de0023fe281b&ids=5e13eff05a2f0e001f946b35&ids=5df99d93716cfa0022cbe5ef&from=2022-09-24&to=2022-09-24&fields=status
Response
Object of calendar ids, where each id is an array of day objects.
Update calendars
HTTP Request
PUT /listings/calendars
Body Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| listings | Required | Array of ids of listings to update, or a single id. | `` |
| from | Required | Update dates starting from this date. Format: yyyy-mm-dd. |
"2016-01-10" |
| to | Required | Update dates ending at this date. Format: yyyy-mm-dd. |
"2016-01-11" |
| status | --- | New status, enum: available, unavailable. |
available |
| price | --- | New price, in the listing's currency. | 100 |
| minNights | Number | New min nights value" | '2' |
| note | --- | Note to add to those dates. |
The API can recieve an array with the above params for multiple listing and days update, example: [{"listingId":"LISTINGID1","from":"2020-01-13","to":"2020-01-16","price":70},{"listingId":"LISTINGID1","from":"2020-04-17","to":"2020-04-18","price":75},{"listingId":"LISTINGID2","from":"2020-03-19","to":"2020-03-23","price":70}]
Response
OK
Reservations
The reservation object
{
"_id": "595fe29f4ab86112341425ac",
"daysInAdvance": 39,
"accountId": "55b9f9b5393dfe0e0023455d",
"listingId": "582df199dd162a040123542",
"guestId": "595fe29c4ab861100023423a",
"status": "confirmed",
"confirmationCode": "EXAMPLE",
"checkInDateLocalized": "2017-08-16",
"checkOutDateLocalized": "2017-08-28",
"guestsCount": 2,
"source": "Booking.com",
"checkIn": "2017-08-16T13:00:00.000Z",
"checkOut": "2017-08-28T09:00:00.000Z",
"nightsCount": 12,
"confirmedAt": "2017-07-07T19:35:59.896Z",
"keyCode": "12345",
"customFields": [
{
"fieldId": "57569cf62ed4400e001678fa",
"value": "New",
"_id": "595fe2a04ab8611000a525b0"
}
],
"log": [
{
"event": "Reservation was updated",
"by": "Me",
"_id": "595fe9660b9b6e10001649d2",
"changes": [
{
"field": "customFields 1 _id",
"_id": "595fe9660b9b6e10001649e5",
"diff": [
{
"value": "595fe9650b9b6e10001649d1",
"added": true,
"_id": "595fe9660b9b6e10001649e6"
}
]
}
],
"at": "2017-07-07T20:04:54.058Z"
}
],
"review": {
"shouldReview": true
},
"money": {
"currency": "EUR",
"hostPayout": 1119,
"guestTotalPrice": 1119,
"alreadyPaid": 0,
"fareAccommodation": 1079,
"fareCleaning": 40,
"ownerRevenue": 718.5,
"commissionIncTax": 214.5,
"commissionTax": 37.23,
"commissionTaxPercentage": 21,
"commission": 177.27,
"commissionFormula": "net_income + 50",
"netIncome": 933,
"netIncomeFormula": "round(host_payout+fare_cleaning)",
"isFullyPaid": false,
"balanceDue": 1119,
"paymentsDue": 0,
"totalPaid": 0,
"totalRefunded": 0,
"subTotalPrice": 1119,
"hostPayoutUsd": 1301.786437223414,
"autoPaymentsPolicy": [],
"payments": [],
"invoiceItems": [
{
"title": "Accommodation fare",
"amount": 1079,
"currency": "EUR",
"isLocked": true,
"_id": "595fe29f4ab8611000a525ad"
},
{
"title": "Additional invoice item (optional)",
"amount": 10,
"currency": "EUR",
"type": "MANUAL",
"_id": "595fe29f4ab8611000a525a1"
}
]
},
"integration": {
"_id": "56cd9ab369a2100e00742341",
"platform": "rentalsUnited",
"rentalsUnited": {
"id": 129132421,
"listingId": 98920,
"channelReservationId": "1906924521"
}
},
"createdAt": "2017-07-07T19:35:59.900Z",
"plannedArrival": "15:00",
"plannedDeparture": "8:00",
"listing": {
"_id": "582df199dd162a04002c0693",
"title": "Industrial and Minimal Mansion",
"address": {
"full": "The full address"
},
"picture": {
"thumbnail": "//guestybookings.s3.amazonaws.com/listings/thumbnail_234161096.jpg"
},
"nickname": "nickname example"
},
"guest": {
"_id": "595fe29c4ab8611000a525aa",
"email": "example@example.com",
"hometown": "76 grand drive City: auckland",
"fullName": "Sara Duma",
"phone": "447537986159",
"picture": {}
}
}
| Attribute | Type | Description |
|---|---|---|
| _id | String | Unique id |
| accountId | String (ObjectId) | |
| listingId | String (ObjectId) | |
| createdAt | Date | |
| lastUpdatedAt | Date | |
| closedAt | Date | |
| confirmedAt | Date | |
| alteredAt | Date | |
| canceledAt | Date | |
| keyCode | String | Keycode for the reservation |
| canceledBy | String | |
| importedAt | Date | |
| integration | integration Object |
(see below) |
| status | Enum | inquiry, declined, expired, canceled, closed, reserved, confirmed, checked_in, checked_out, awaiting_payment |
| confirmationCode | String | |
| checkIn | Date | |
| checkInDateLocalized | String | |
| checkOut | Date | |
| checkOutDateLocalized | String | |
| plannedArrival | String | Planned time of arrival: HH:mm |
| plannedDeparture | String | Planned time of departure: HH:mm |
| nightsCount | Number | |
| daysInAdvance | Number | |
| guestsCount | Number | |
| cancellationPolicy | String | |
| instantBook | Boolean | |
| guestId | String (ObjectId) | |
| isReturningGuest | Boolean | |
| money | money Object |
(see below) |
| review | review Object |
(see below) |
| notes | notes Object |
(see below) |
| log | log Object |
(see below) |
| source | String | The source of the reservation |
| customFields | [customFields Object] | (see below) |
The integration object
| Attribute | Type | Description |
|---|---|---|
| _id | String | |
| platform | Enum | airbnb, rentalsUnited, manual, bookingCom or homeaway (in development) |
| airbnb | object | Details related to Airbnb (id, listingId, guestId) |
| rentalsUnited | Object | Details related to RU (id, listingId) |
| bookingCom | Object | Details related to bookingCom (id, listingId, reservationId) |
| homeAway | Object | Coming soon! |
The money object
| Attribute | Type | Description |
|---|---|---|
| currency | String | |
| fareAccommodation | Number | |
| fareCleaning | Number | |
| subTotalPrice | Number | |
| guestServiceFee | Number | |
| guestTaxes | Number | |
| guestTotalPrice | Number | |
| alreadyPaid | Number | |
| hostServiceFee | Number | |
| hostTaxes | Number | |
| hostPayout | Number | |
| hostPayoutUsd | Number | |
| hostOriginalPayout | Number | if reservation is canceled. |
| netIncomeFormula | String | |
| netIncome | Number | |
| commissionFormula | String | |
| commission | Number | |
| commissionTaxPercentage | Number | |
| commissionTax | Number | |
| commissionIncTax | Number | |
| ownerRevenue | Number | |
| invoiceItems | [invoiceItems] | (see below) |
| payments | [payments] | (see below) |
The payment object
{
"receiptId": 14464234,
"paymentMethodId": "58a48a4fea2a13ea9fda5873",
"guestId": "59a0cccb9437ed04001fa6df",
"confirmationCode": "194017946",
"amount": 1347,
"currency": "GBP",
"shouldBePaidAt": "2017-08-03T13:00:00.000Z",
"paidAt": "2017-08-03T13:00:00.000Z",
"_id": "59a24239a992940400fd8e49",
"receiptTargets": [],
"attempts": [],
"createdAt": "2017-08-27T03:53:29.142Z",
"refunds": [],
"status": "SUCCEEDED"
}
| Attribute | Type | Description |
|---|---|---|
| paymentMethodId | String (ObjectId) | |
| status | String | |
| refunds | [refunds] | |
| ---amount | Number | |
| ---createdAt | Date | |
| ---status | String | |
| ---note | String | |
| guestId | String (ObjectId) | |
| confirmationCode | String | |
| amount | Number | |
| currency | Enum | |
| createdAt | Date | |
| shouldBePaidAt | Date | |
| paidAt | Date | |
| attempts | [attempts] | |
| ---createdAt | Date | |
| ---status | String | |
| ---payload | Object | attempt payload |
| ---error |
The invoiceItems object
| Attribute | Type | Description |
|---|---|---|
| title | String | |
| amount | Number | |
| currency | String | |
| isLocked | Boolean | |
| type | Enum | TAX, CLEANING_FEE, PET_FEE, ADDITIONAL, UNKNOWN, OTHER, MANUAL, CANCELLATION_FEE, GUEST_FEE, ACTIVITY, DEPOSIT, MISC, PROTECTION, ACCOMMODATION_FARE, DISCOUNT |
The review object
{
"shouldReview" : true,
"hostReview" : {
"createdAt" : "2017-08-27T03:53:24.535Z",
"public" : "Anies was the perfect guest and we can recommend to other owners without hesitation. We hope we get the opportunity to host them again in the future. Many thanks, Will&Team."
},
"hasGuestReviewed" : true,
"guestReview" : {
"public" : "The place is very clean. A nice high-ceilinged open-plan flat with huge living area and a modern kitchen. Walking distance to Angel and Exmouth Market. My parents and I had an enjoyable stay there.",
"private" : "",
"createdAt" : "2017-08-27T03:53:25.821Z"
}
}
| Attribute | Type | Description |
|---|---|---|
| shouldReview | Boolean | deprecated |
| hostReview | ||
| guestReview | ||
| hasGuestReviewed | ||
| expiresAt |
The notes object
| Attribute | Type | Description |
|---|---|---|
| cleaning | String | |
| guest | String | |
| other | String |
The customFields object
| Attribute | Type | Description |
|---|---|---|
| fieldId | ObjectId | Ref to the definition (account.customFields._id) |
| value | Mixed | Type is according to the definition |
The log object
{
"event": "Reservation was updated",
"by": "Me",
"_id": "595fe9660b9b6e10001649d2",
"changes": [
{
"field": "customFields 1 _id",
"_id": "595fe9660b9b6e10001649e5",
"diff": [
{
"value": "595fe9650b9b6e10001649d1",
"added": true,
"_id": "595fe9660b9b6e10001649e6"
}
]
}
],
"at": "2017-07-07T20:04:54.058Z"
}
| Attribute | Type | Description |
|---|---|---|
| event | String | |
| description | String | |
| by | String | |
| at | Date | |
| changes | [changes] | |
| ---fields | String | |
| ---diff | [diff] | |
| ------- value | String | |
| ------- added | Boolean | |
| ------- removed | Boolean |
Create a reservation
Response
{
"__v": 0,
"lastUpdatedAt": "2017-09-13T14:31:37.460Z",
"listingId": "59b928bb8e6bb31000219e58",
"checkInDateLocalized": "2017-09-15",
"checkOutDateLocalized": "2017-09-18",
"status": "inquiry",
"accountId": "563e0b6a08a2710e00057b82",
"guestId": "59b9414932123a1000b7cd54",
"guestsCount": 1,
"source": "Manual",
"checkIn": "2017-09-15T12:00:00.000Z",
"checkOut": "2017-09-18T08:00:00.000Z",
"nightsCount": 3,
"checkInIsFlexible": true,
"checkOutIsFlexible": true,
"_id": "59b9414932123a1000b7cd55",
"customFields": [],
"confirmedPreBookings": [],
"log": [],
"pendingTasks": [],
"review": {
"shouldReview": true
},
"money": {
"ownerRevenue": 450,
"commissionIncTax": 50,
"commissionTax": 0,
"commissionTaxPercentage": 0,
"commission": 50,
"commissionFormula": "net_income*0.1",
"netIncome": 500,
"netIncomeFormula": "host_payout",
"isFullyPaid": false,
"balanceDue": 500,
"paymentsDue": 0,
"totalPaid": 0,
"totalRefunded": 0,
"fareAccommodation": 500,
"currency": "USD",
"hostPayout": 500,
"subTotalPrice": 500,
"hostPayoutUsd": 500,
"autoPaymentsPolicy": [],
"payments": [],
"invoiceItems": [
{
"title": "Accommodation fare",
"amount": 500,
"currency": "USD",
"isLocked": true,
"_id": "59b9414932123a1000b7cd56"
}
]
},
"integration": {
"_id": "5784a3cc64ce9c0e00ecaf1e",
"platform": "manual",
"limitations": {
"availableStatuses": []
}
},
"createdAt": "2017-09-13T14:31:37.452Z",
"id": "59b9414932123a1000b7cd55"
}
HTTP Request
POST /reservations
Validations
The field money.invoiceItems is optional. But if it exists in request body, the field money.invoiceItems.type is required for every invoice item.
Body
| Parameter | Default |
|---|---|
| listingId | Required |
| checkInDateLocalized | Required |
| checkOutDateLocalized | Required |
| status | Required |
| money | Required |
| ---fareAccommodation | Required |
| ---fareCleaning | Optional |
| ---guestTaxes | Optional |
| ---currency | Required |
| ---invoiceItems | Optional |
| -------type | |
| guestId | Either ID or Details |
| guest | See Below |
| ---firstName | |
| ---lastName | |
| ---phone |
Guest
There are two options for defining guest.
1) Pass the guestId property. If a gest exists with the given ID it will be attached to the reservation. If there is no guest with such ID "Guest not found" error will be returned. Please note that if you use separate endpoint to create guest first, it will take some time before it is available for reading because we use separate clusters for read and write operations.
2) Pass the guest object. You can define guest right in "create reservation" request. The guest will be automatically created and attached to reservation. If you send the same object next time it will be matched to existing and it will not create a duplicate.
You shouldn't pass both properties at the same time. If you don't pass any of the properties, a guest will be created without any info. But it will still be attached to your account/apiKey.
Validations
System will make sure reservation is according to terms (min, max nights, any other terms), and decline otherwise (401), unless flag (ignoreTerms). System will make sure calendar is available, and decline otherwise (401), unless flag (ignoreCalendar).
Example
Body
{"listingId": "59b928bb8e6bb31000219e58", "checkInDateLocalized": "2017-09-15", "checkOutDateLocalized": "2017-09-18", "status": "inquiry", "money":{"fareAccommodation": "500", "currency": "USD"}, "guest":{"firstName": "Tony", "lastName"": "Stark", "phone": "+7777777", "email": "tony@stark.com"}}
Response
The inserted object.
Retrieve a reservation
HTTP Request
GET /reservations/:id
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| fields | null |
Selection of fields, separated by space. When null retrieve the main properties of the object. We recommend always specifying the specific fields you'd like to receive to ensure that you get them. Please see the full list above. |
checkIn status |
Response
Reservation object
Update a reservation
HTTP Request
PUT /reservations/:id
Body
Selected fields to update.
limitations;
checkIn and checkOut can not be amended, in order to update these values, please use checkInDateLocalized and plannedArrival in order to amened check in details and checkOutDateLocalized and plannedDeparture to update check out details.
Validations: The System will make sure reservation is according to terms (min, max nights, any other terms), and decline otherwise (401), unless flag (ignoreTerms=true). The System will make sure calendar is available, and decline otherwise (401), unless flag (ignoreCalendar=true).
Response
Retrieve the updated reservation, selection of fields that were sent in body.
Add a payment for reservation
HTTP Request
POST /reservations/:id/payments
Body
| Parameter | Default | Description |
|---|---|---|
| paymentMethod | Required | |
| ---method | Required | 'CASH','CREDIT','DEBIT','ECHECK','STRIPE' |
| ---_id | Required if method is "STRIPE" | |
| amount | ||
| shouldBePaidAt | ||
| paidAt | ||
| note | ||
| creditCard | Required if method is "STRIPE" |
Example
Body
{
"amount": 10,
"shouldBePaidAt": "2020-05-19T17:36:58.600Z",
"creditCard": "paymentMethodId",
"paymentMethod": {
"method": "STRIPE",
"saveForFutureUse": true,
"_id": "paymentMethodId"
}
}
Response
Retrieve the updated reservation, selection of money.payments field.
Update an existing payment
HTTP Request
PUT /reservations/:id/payments
Body
| Parameter | Default | Description |
|---|---|---|
| paymentId | Required | the _id of the payment to update |
| paymentMethod | Required | |
| ---method | Required | 'CASH','CREDIT','DEBIT','ECHECK','STRIPE' |
| ---_id | ||
| amount | ||
| shouldBePaidAt | ||
| paidAt | ||
| note | ||
| stripePaymentMethodToken |
Example
Body
{"paymentId": "5ea809dbef629f00311ee947","paymentMethod": {"method": "STRIPE"}}
Response
Retrieve the updated reservation, selection of money.payments field.
Cancel an existing payment
HTTP Request
PUT /reservations/:id/payments/:paymentId
Body
| Parameter | Default | Description |
|---|---|---|
| paymentId | Required | the _id of the payment to cancel |
| paymentMethod | Required | |
| ---method | Required | 'CASH','CREDIT','DEBIT','ECHECK','STRIPE' |
| ---_id | Required | |
| status | Required | "CANCELLED" |
Example
Body
{
"paymentId": "5d80c3254c650a001faacdb4",
"paymentMethod": {
"_id": "589894a91d756b9c47ce1e87",
"method": "CASH"
},
"status":"CANCELLED"
Response
Retrieve the updated payments object with the updated status.
{
"_id": "5884ebaaded55810009bb38a",
"money": {
"payments": [
{
"paymentMethodStatus": "ACTIVE",
"isAuthorizationHold": false,
"status": "CANCELLED",
"refunds": [
{
"createdAt": "2019-07-23T18:27:24.052Z",
"_id": "5d37518c029c950021095f10",
"amount": 200,
"status": "SUCCEEDED"
}
],
"authorizationHoldCaptures": [],
"createdAt": "2019-07-23T18:27:04.928Z",
"attempts": [],
"receiptTargets": [
{
"sentAt": [
"2020-04-19T20:36:55.638Z"
],
"_id": "5e9cb667972321002be33411",
"email": "allan@guesty.com"
}
],
"_id": "5d3751785007c70020938d34",
"amount": 200,
"paymentMethodId": "589894a91d756b9c47ce1e87",
"guestId": "58517197f0a29b1000a38053",
"currency": "USD",
"shouldBePaidAt": "2019-07-23T18:27:04.928Z",
"paidAt": "2019-07-23T18:27:04.928Z",
"receiptId": 17280128,
"guest": {
"_id": "58517197f0a29b1000a38053",
"email": "aviad_14@guesty.com",
"fullName": "Aryah Stark"
},
"paymentMethod": {
"_id": "589894a91d756b9c47ce1e87",
"method": "CASH"
}
},
{
"paymentMethodStatus": "ACTIVE",
"isAuthorizationHold": false,
"status": "CANCELLED",
"_id": "5d80c3254c650a001faacdb4",
"refunds": [],
"authorizationHoldCaptures": [],
"createdAt": "2019-09-17T11:27:33.757Z",
"attempts": [],
"receiptTargets": [],
"amount": 100,
"paymentMethodId": "589894a91d756b9c47ce1e87",
"guestId": "58517197f0a29b1000a38053",
"currency": "USD",
"shouldBePaidAt": "2019-09-17T11:27:33.757Z",
"paidAt": "2019-09-17T11:27:33.757Z",
"receiptId": 17497347,
"guest": {
"_id": "58517197f0a29b1000a38053",
"email": "aviad_14@guesty.com",
"fullName": "Aryah Stark"
},
"paymentMethod": {
"_id": "589894a91d756b9c47ce1e87",
"method": "CASH"
}
},
{
"paymentMethodStatus": "ACTIVE",
"isAuthorizationHold": false,
"status": "SUCCEEDED",
"refunds": [],
"authorizationHoldCaptures": [],
"createdAt": "2020-04-14T20:59:10.144Z",
"attempts": [],
"receiptTargets": [],
"_id": "5e96241efdd1c00029651b91",
"amount": 128.73,
"paymentMethodId": "589894a91d756b9c47ce1e87",
"guestId": "58517197f0a29b1000a38053",
"currency": "USD",
"shouldBePaidAt": "2020-04-14T20:59:10.086Z",
"paidAt": "2020-04-14T20:59:10.086Z",
"receiptId": 18299424,
"guest": {
"_id": "58517197f0a29b1000a38053",
"email": "aviad_14@guesty.com",
"fullName": "Aryah Stark"
},
"paymentMethod": {
"_id": "589894a91d756b9c47ce1e87",
"method": "CASH"
}
}
]
}
}
Add an new Invoice item
HTTP Request
POST /reservations/:id/invoiceItems
Body
| Parameter | Default | Description |
|---|---|---|
| title | Required | name to be displayed |
| amount | Required | amount to be add |
| description | Required | a short description (may be "") |
Response
Retrieve the updated reservation, selection of money.payments field.
Search reservations
{
"count": 3,
"limit": 25,
"skip": 0,
"results": [
{
"_id" : "5655b3dec03ca814016a5038",
"createdAt" : "2014-12-17T08:33:44.510Z",
"integration" : {
"platform" : "airbnb",
"_id" : "53eb27386b51b257846cdd11",
"airbnb" : {
"listingId" : 1148991,
"guestId" : 3648962
}
},
"status" : "inquiry",
"guestId" : "5655b3debf1fab1507921c33",
"listingId" : "5319674d4930a7f09b075696",
"checkIn" : "2013-11-21T22:00:00.000Z",
"checkOut" : "2013-11-26T22:00:00.000Z",
"checkInDateLocalized" : "2013-11-22",
"checkOutDateLocalized" : "2013-11-27",
"guestsCount" : 1,
"money" : {
"ourCommission" : 0,
"ownerRevenue" : 0.0,
"userRevenue" : 0,
"userRevenueFormula" : "host_payout",
"netIncome" : 0,
"netIncomeFormula" : "fare_accommodation + fare_cleaning",
"commission" : 0,
"commissionFormula" : "net_income*0.2",
"commissionIncTax" : 0,
"commissionTax" : 0,
"commissionTaxPercentage" : 16
},
"accountId" : "5319674d4930a7f09b075695",
"source" : "Airbnb",
"lastUpdatedAt" : "2016-04-19T19:50:54.292Z"
}
]
}
HTTP Request
GET /reservations
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| viewId | null |
Pull a specific view (view is a saved settings of accountId, filters, fields, sort) | 556d95083c59ae58e3fdd8f4 |
| filters | [{"field":"status", "operator":"$in", "value":["confirmed"]},{"field":"checkIn", "operator":"$gt", "context":"now", "value":0}] |
Array of filters to query by (See below) | See default |
| fields | checkIn checkOut confirmationCode guest.fullname listing.title |
Selection of fields, separated by space | See default |
| sort | checkIn |
The field to sort by. Preppend - for DESC. |
checkIn/-checkIn |
| limit | 25 |
Pagination | 25 |
| skip | 0 |
Pagination | 0 |
Filters
{
"field": "checkIn",
"operator": "$gt",
"value": 0,
"context": "now"
}
| Parameter | Default | Description | Example |
|---|---|---|---|
| field | Required | Subject of the filter | |
| operator | Required | Enhanced MongoDB comparison operator: $eq, $not, $contains, $notcontains, $gt, $lt, $between | |
| value | Required | Value to filter by. | |
| context | null |
Optional preprocessing. Options are now, createdAt, confirmedAt, canceledAt, alteredAt. When given, the date in value is relative to the context. |
Response
Reservation objects
Export as CSV
HTTP Request
GET /reservations.csv
Same as /reservations but results are returned as a downloadable csv file
Send results in email
HTTP Request
POST /reservations.email
Same as /reservations but results are sent as an email
Body Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| to | Required | Address of recipient | koby@guesty.com |
Approve a pending booking request
{
"status": "confirmed",
"_id": "5a7306914976200093ee9ebf"
}
HTTP Request
POST /reservations/:id/approve
Response
Reservation object - _id and status fields.
Decline a pending booking request
{
"status": "declined",
"_id": "5a7307182ffb49005b0bff9a"
}
HTTP Request
POST /reservations/:id/decline
Response
Reservation object - _id and status fields.
Get all reservation's custom fields
HTTP Request
GET /reservations/:Id/custom-fields/
Get a reservation's custom field
HTTP Request
GET /reservations/:Id/custom-fields/{field_id}
Update Reservation's Custom Fields
HTTP Request
PUT /reservations/{reservation_id}/custom-fields/
Body
{
"customFields": [
{
"fieldId": "your_field_id",
"value": 3
},
{
"fieldId": "your_field_id",
"value": "london apartment"
},
{
"fieldId": "your_field_id",
"value": "wifipassword"
}
]
}
Parameter | Default | Description | Example
--------- | ------- | ----------- | -------
fieldId | Requiered | ------- | 5f744b491af840002ca636a2
value | required | The text field name | "wifipassword"
Response
The updated object.
Delete Reservation's Custom Fields
HTTP Request
DELETE /reservations/{reservation_id}/custom-fields/{{field_id}}
Owners Reservations
The owners-reservations object
{
"_id": "5e6a2110ec00800028ede79e",
"status": "confirmed",
"source": "owners portal",
"ownerId": "5dc1794a6aed080024e50521",
"accountId": "596f6fe706112710005d96ff",
"listingId": "5988346d3c31bf0f00747eb6",
"checkIn": "2020-03-19 15:00:00",
"checkOut": "2020-03-20 10:00:00",
"note": "test note",
"createdAt": "2020-03-12T11:46:24.118Z",
"__v": 0,
"id": "5e6a2110ec00800028ede79e"
}
| Attribute | Type | Description |
|---|---|---|
| _id | String | Unique id |
| status | Enum | inquiry, declined, expired, canceled, closed, reserved, confirmed, checked_in, checked_out, awaiting_payment |
| source | String | |
| ownerId | String | ObjectId |
| accountId | String | ObjectId |
| listingId | String | ObjectId |
| checkIn | String | YYYY-MM-DD HH:MM:SS |
| checkOut | String | YYYY-MM-DD HH:MM:SS |
| note | String | |
| createdAt | Date | ISO |
| __v | Number | |
| id | String | Unique id |
The owners-reservations full object
{
"status": "canceled",
"source": "owners portal",
"_id": "5e6a28e32275770029393bac",
"ownerId": "5dc1794a6aed080024e50521",
"accountId": "596f6fe706112710005d96ff",
"listingId": "5988346d3c31bf0f00747eb6",
"checkIn": "2020-03-17 15:00:00",
"checkOut": "2020-03-18 10:00:00",
"createdAt": "2020-03-12T12:19:47.812Z",
"__v": 1,
"checkInDateLocalized": "Mar 17, 2020",
"checkOutDateLocalized": "Mar 18, 2020",
"lastUpdatedAt": "2020-03-12T12:19:47.824Z",
"listing": {
"address": {
"street": "Place Cendrillon",
"zipcode": "78280",
"lng": 2.0753368,
"lat": 48.7747508,
"country": "France",
"state": "Île-de-France",
"city": "Guyancourt",
"full": "Place Cendrillon, 78280 Guyancourt, France",
"searchable": "Guyancourt, Île-de-France, France"
},
"tags": [
"dungeon",
"aviv"
],
"_id": "5988346d3c31bf0f00747eb6",
"bathrooms": 1,
"title": "my castle 1 test property",
"bedrooms": 1,
"accommodates": 4,
"propertyType": "Apartment",
"roomType": "Entire home/apt",
"beds": 1,
"nickname": "my private dungeon12",
"areaSquareFeet": 12
},
"nightsCount": 1,
"note": "",
"ownerId": {
"locale": "en-US",
"_id": "5dc1794a6aed080024e50521",
"email": "test@test.com",
"fullName": "test test"
},
"plannedArrival": "03:00 PM",
"plannedDeparture": "10:00 AM",
"canceledAt": "2020-03-12T12:20:05.741Z",
"id": "5e6a28e32275770029393bac"
}
| Attribute | Type | Description |
|---|---|---|
| _id | String | Unique id |
| status | Enum | confirmed, checked_in, checked_out, inquiry, declined, canceled, closed |
| source | String | |
| ownerId | String | ObjectId |
| accountId | String | ObjectId |
| listingId | String | ObjectId |
| checkIn | String | |
| checkOut | String | |
| createdAt | Date | ISO |
| __v | Number | |
| checkInDateLocalized | String | |
| checkOutDateLocalized | String | |
| lastUpdatedAt | Date | ISO |
| listing | ListingInfo |
object |
| nightsCount | Number | |
| note | String | |
| owner | OwnerInfo |
object |
| plannedArrival | String | Planned time of arrival: HH:mm |
| plannedDeparture | String | Planned time of arrival: HH:mm |
| cancelledAt | Date | ISO |
| id | String | Unique id |
The OwnerInfo object
{
"locale": "en-US",
"_id": "5dc1794a6aed080024e50521",
"email": "test@test.com",
"fullName": "test test"
}
| Attribute | Type | Description |
|---|---|---|
| _id | String | ObjectId |
| locale | String | |
| 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 |
example
{ "stripeCardToken": "pm_...", "skipSetupIntent": false }
Side-effect
If there's auto-payments with payment method CASH (no payment method defined in the UI), then they will be changed to the added payment method automatically
Retrieve payment methods
Response
[
{
"saveForFutureUse": true,
"status": "ACTIVE",
"type": "PHYSICAL",
"_id": "paymentMethodId",
"accountId": "accountId",
"method": "STRIPE",
"payload": {
"id": "pm_...",
"object": "payment_method",
"customer": "cus_...",
"name": "test test",
"address_city": null,
"address_country": null,
"address_line1": null,
"address_line2": null,
"address_state": null,
"address_zip": null,
"address_line1_check": null,
"address_zip_check": null,
"cvc_check": "pass",
"brand": "visa",
"country": "US",
"exp_month": 4,
"exp_year": 2024,
"fingerprint": "6i2ad2EHQpQJ8PeH",
"funding": "credit",
"last4": "4242"
},
"createdAt": "2020-05-20T10:12:39.438Z",
"last4": "4242",
"brand": "visa",
"__v": 0
}
]
HTTP Request
GET /guests/:id/payment-methods
Response
Payment methods list
Phone Book Contacts
The contact object
{
"_id": "57e9437fd0b2c00f00d3d808",
"phone": "972541723456",
"fullName": "(GodOfWar) Sergey Grinblat",
"preferredContactMethod": "email",
"firstName": "Sergey",
"lastName": "Grinblat",
"company": "Guesty",
"notes": "Examples notes",
"title": "GodOfWar",
"email": "example@guesty.com",
"accountId": "563e0b6a08a2710e00057b82",
"phones": [
"972541723456"
],
"emails": [
"example@guesty.com"
],
"__v": 1
}
| Attribute | Type | Description |
|---|---|---|
| _id | String | Unique id |
| accountId | ObjectId (String) | Owner |
| firstName | String | |
| lastName | String | |
| fullName | String | |
| nickname | String | |
| title | String | |
| company | String | |
| picture | Picture (Object) | (see below) |
| emails | Array (String) | |
| phones | Array (String) | |
| preferredContactMethod | String | |
| 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": 1,
"cursor": {
"after": "MjAyMC0wNy0wOVQxMDowMzozOS43ODBaXzVmMDZlYjdiYzVkODk4MDAyYWMwNTM2Nw==",
"before": "MjAyMC0wNy0xMFQxMDoyMToxMy4yODNaXzVmMDg0MTE5MjhlZjlmMDAyODJjMTVhYg==",
}
}
}
HTTP Request
GET /communication/conversations/:id/posts
Authorization
Only accessible to Admin or User tokens.
accountId is taken from token and not from request.
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| sort | -createdAt |
Sorting | -createdAt |
| limit | 25 |
Pagination, max: 100 | 25 |
| cursorAfter | '' |
Pagination | MjAyMC0wNy0wOVQxMDowMzozOS43ODBaXzVmMDZlYjdiYzVkODk4MDAyYWMwNTM2Nw== |
| cursorBefore | null |
Pagination | MjAyMC0wNy0xMFQxMDoyMToxMy4yODNaXzVmMDg0MTE5MjhlZjlmMDAyODJjMTVhYg== |
cursorAfter and cursorBefore are not allowed to be used at the same time in one request.
Response
Post object.
Add new message to conversation without sending it
{
"status": 200,
"data": {
"module": {
"to": [],
"cc": [],
"bcc": [],
"templateValues": [],
"type": "email"
},
"_id": "5f465cea933726002b6f414b",
"body": "Add message without sending",
"conversationId": "5815f92df4ff4b0f005f053b",
"createdAt": "2020-08-26T13:00:26.329Z",
"attachments": [],
}
}
HTTP Request
POST /communication/conversations/:id/posts
Body
| Parameter | Default | Description |
|---|---|---|
| module | Required | |
| --type | Required | sms, email, note, log, whatsapp, airbnb2 |
| body | Required | The message itself |
| sentBy | host |
host, guest |
Authorization
Only accessible to Admin or User tokens.
accountId is taken from token and not from request.
Example
Body
{"module":{"type":"note"},"body":"This is new note"}
Response
The created object.
Send new message
{
"status": 200,
"data": {
"module": {
"to": [],
"cc": [],
"bcc": [],
"templateValues": [],
"type": "email"
},
"_id": "5f465cea933726002b6f414b",
"body": "Add message without sending",
"conversationId": "5815f92df4ff4b0f005f053b",
"createdAt": "2020-08-26T13:00:26.329Z",
"attachments": [],
}
}
HTTP Request
POST /communication/conversations/:id/send-message
Body
| Parameter | Default | Description |
|---|---|---|
| module | Required | |
| --type | Required | platform, sms, email, note, log, whatsapp, airbnb2 |
| --cc | for email module | array of email addresses |
| --bcc | for email module | array of email addresses |
| body | Required | The message itself |
Module type platform posts will be sent through Airbnb for conversations with Airbnb guests and through Email for conversations with non Airbnb guests.
Authorization
Only accessible to Admin or User tokens.
accountId is taken from token and not from request.
Example
Body
{"module":{"type":"sms"},"body":"This is new message"
Response
The created object.
Error objects
Validation error
Status: 400 Bad Request
{
"error": {
"code": "VALIDATION_ERROR",
"message": "\"conversationId\" with value \"1\" fails to match the valid mongo id pattern",
"data": {
"details": [
{
"message": "\"conversationId\" with value \"1\" fails to match the valid mongo id pattern",
"path": [
"conversationId"
],
"type": "string.pattern.name",
"context": {
"name": "valid mongo id",
"regex": {},
"value": "1",
"label": "conversationId",
"key": "conversationId"
}
}
]
}
}
}
Forbidden error
Status: 403 Forbidden
{
"error": {
"code": "FORBIDDEN",
"message": "Forbidden"
},
"status": 403,
"data": {}
}
500 error
Status: 500 Internal Server Error
{
"error": {
"message": "Request failed with status code 500"
},
"status": 500,
"data": {}
}
Billing - Invoices
Invoice object
| Attribute | Type | Description |
|---|---|---|
| _id | String | Unique id |
| accountId | String | Id of the user owning this invoice |
| methodId | String | Id of the payment method. |
| method | Enum | Can be any supported payment method, currently only stripe. (It is here to make it permanent as method can be deleted) |
| methodText | String | Representable name of the payment method. e.g. "Visa 7243" (It is here to make it permanent as method can be deleted) |
| status | Enum | Can be succeeded or failed or fully-refunded. |
| amount | Number | The amount paid |
| currency | Enum | Any supported currency. |
| creditApplied | Number | The amount of credit that was used in this invoice. |
| description | String | Text describing the invoice. |
| createdAt | Date | The date this invoice was created. |
| refundedAt | Date | The date this invoice was last refunded, even partially. |
| refundedAmount | Number | The amount this invoice has been refunded. |
| receiptExtraContent | String | Text to add to the receipt, usually defaulted to payment method. (It is here to make it permanent.) |
| error | String | If there has been an error (status is failed) this is its description |
| stripe | Object | An external object with details of this transaction. |
| refundedBy | String | |
| refundedReason | String |
List invoices
{
"count": 1,
"limit": 25,
"skip": 0,
"results": [
{
"_id": "595a632a420d0d04002682b9",
"accountId": "563e0b6a08a2710e00057b82",
"amount": 70,
"currency": "USD",
"createdAt": "2017-07-03T15:30:50.164Z",
"__v": 0,
"creditApplied": 2,
"status": "succeeded"
}
]
HTTP Request
GET /billing/invoices
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| accountId | null for admin token, connected account for user token |
with admin token, Unavailable with user token. | 531968414930a7f09b075800 |
| methodId | null |
Limit results to specific payment methods. Can send an array. | 531968414930a7f09b075800 |
| include_failed | true |
Boolean | true |
| fields | null |
Selection of fields, separated by space | amount createdAt |
| sort | -createdAt |
Field to sort by. Prepend - for DESC. |
createdAt |
| limit | 25 | Pagination, max: 100 | 25 |
| skip | 0 | Pagination | 0 |
Response
Invoice objects
Upcoming invoice
{
"accountId": "563e0b6a08a2710e00057b82",
"status": "upcoming",
"amount": 28,
"items": {
"count": 1,
"limit": 25,
"skip": 0,
"results": [
{
"components": [
{
"name": "SOFTWARE",
"planType": "RESERVATION_COMMISSION",
"value": 1.5,
"isLocked": true,
"_id": "588e042f8b66181000065dec",
"amount": 28
}
],
"isMinimumFee": false,
"planType": "RESERVATION_COMMISSION",
"confirmationCode": "MEQKll3",
"source": "Manual",
"checkIn": "2017-06-26",
"listing": {
"_id": "59213fbca3af9e1000228c09",
"nickname": "Nadav Test Listing",
"title": "Nadav's Best Awesome Listing"
},
"reservationId": "593903b35487aa1000944c85"
}
]
},
"currency": "USD"
}
HTTP Request
GET /billing/invoices/upcoming
Used to get the customer upcoming invoices for each of his payment methods It is a little different since it is not really an invoice object yet. Invoices are created only upon payment. Also unlike invoices/list, each invoice also has its invoice items. Pagination is also available.
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| methodId | --- | Required Limit results to the invoice of specific payment method. null for unassociated method's invoice (in case there is no payment method). |
531968414930a7f09b075800 |
| limit | 10 |
Pagination for invoice items | 10 |
| skip | 0 |
Pagination for invoice items | 0 |
Response
List of invoice-like objects, where each item is a different payment method. status is pending.
Not included fields are creditApplied, createdAt, paidAt, refundedAt, refundedAmount, receiptExtraContent, error, stripe.
The items object
| Attribute | Type | Description |
|---|---|---|
| count | Number | Total count of results |
| skips | Number | Amount of results to skip |
| limit | Number | Maximum number of invoice items to include in this object, always 10. For more, use invoice items.list |
| results | Array | Array of invoice item objects |
Download invoices receipts as pdf
HTTP Request
POST /billing/invoices/download.pdf
Body
| Parameter | Default | Description | Example |
|---|---|---|---|
| invoiceId | --- | Required What invoices to download. Can send an array. | 531968414930a7f09b075800 |
Response
PDF file of receipts (use pages for multiple receipts) with download headers.
Email invoices
HTTP Request
POST /billing/invoices/email
Sends an email with attached receipt PDF file of receipts (use pages for multiple receipts).
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| invoiceId | --- | Required What invoices to download. Can send an array. | 531968414930a7f09b075800 |
| recipient | --- | Required The email of the recipient. Format Name <email>. |
Koby <koby@guesty.com> |
| message | `` | A message to be included in the email. | See attached receipt |
Response
OK
Retrieve an invoice
{
"_id": "595a632a420d0d04002682b9",
"accountId": "563e0b6a08a2710e00057b82",
"amount": 0,
"currency": "USD",
"createdAt": "2017-07-03T15:30:50.164Z",
"__v": 0,
"creditApplied": 2,
"status": "succeeded"
}
HTTP Request
GET /billing/invoices/:id
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| fields | null |
Selection of fields, separated by space | "amount currency" |
Response
Invoice object
Update an invoice
HTTP Request
PUT /billing/invoices/:id
Body Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| receiptExtraContent | --- | Update the extra content that is added to the receipt. | Guesty Inc. |
| refundedAmount | --- | Used to refund a receipt. This is the amount to refund now. Maximum is the amount-(current)refundedAmount. | 20 |
| logExtraContent | --- | Text that will be added to the update action. For instance, refund reason. | Refund - Unsatisfied |
Response
Updated invoice object
Billing - Invoice Items
Invoice item object
{
"_id": "586395fd5e88fb10000ceaa2",
"accountId": "563e0b6a08a2710e00057b82",
"reservationId": "586395fd5e88fb10000cea9f",
"amount": 0,
"currency": "USD",
"description": "Booking fee - Free - OZVnoAB - Luxury House Near the City - Koby",
"isOurFee": true,
"shouldBePaidAt": "2017-01-28T14:32:10.215Z",
"createdAt": "2016-12-28T10:37:49.524Z",
"__v": 0,
"components": [],
"paidAt": "2017-06-12T15:31:04.364Z",
"invoiceId": "593eb3b83e1b3d040060d084"
}
| Attribute | Type | Description |
|---|---|---|
| _id | String | Unique id |
| accountId | String | Id of the user owning this invoice. |
| reservationId | String | Id of the booking associated to this invoice item. |
| invoiceId | String | Id of the invoice this item was liked to. |
| createdAt | Date | The date this invoice was created. |
| amount | Number | The amount of this charge. |
| currency | Enum | Any supported currency. |
| description | String | Text describing the invoice item. |
| shouldBePaidAt | Date | The expected date of payment. |
| paidAt | Date | The date this invoice was paid. |
| isOurFee | Boolean | Whether it is Guesty fee. |
List invoice items
{
"count": 1,
"limit": 10,
"skip": 0,
"results": [
{
"_id": "586395fd5e88fb10000ceaa2",
"accountId": "563e0b6a08a2710e00057b82",
"reservationId": "586395fd5e88fb10000cea9f",
"amount": 0,
"currency": "USD",
"description": "Booking fee - Free - OZVnoAB - Luxury House Near the City - Koby",
"isOurFee": true,
"shouldBePaidAt": "2017-01-28T14:32:10.215Z",
"createdAt": "2016-12-28T10:37:49.524Z",
"__v": 0,
"components": [],
"paidAt": "2017-06-12T15:31:04.364Z",
"invoiceId": "593eb3b83e1b3d040060d084"
}
]
}
HTTP Request
GET /billing/invoice-items
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| methodId | --- | Limit results to a specific payment method | 531968414930a7f09b075800 |
| invoiceId | --- | Limit results to a specific invoice | 531968414930a7f09b075800 |
| include_paid | true |
Whether to filter fo just paid items | |
| include_unpaid | true |
Whether to filter to just unpaid items | |
| fields | null |
Selection of fields, separated by space | "amount" |
| limit | 10 |
Pagination | 10 |
| skip | 0 |
Pagination | 0 |
At least one of accountId, methodId or invoiceId is required.
Response
Object of total count, pagination (limit, skip) and results as array of invoice item objects.
Retrieve an invoice item
{
"_id": "586395fd5e88fb10000ceaa2",
"accountId": "563e0b6a08a2710e00057b82",
"reservationId": "586395fd5e88fb10000cea9f",
"amount": 0,
"currency": "USD",
"description": "Booking fee - Free - OZVnoAB - Luxury House Near the City - Koby",
"isOurFee": true,
"shouldBePaidAt": "2017-01-28T14:32:10.215Z",
"__v": 0,
"paidAt": "2017-06-12T15:31:04.364Z",
"invoiceId": "593eb3b83e1b3d040060d084",
"components": [],
"createdAt": "2016-12-28T10:37:49.524Z"
}
HTTP Request
GET /billing/invoice-items/:id
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| fields | null |
Fields to select. If null, returns all | amount currency |
Download invoice's invoice items as csv
"Description","Amount","Currency","Paid at"
"Booking fee - 2.5% - GYZyAN0 - RU test - nickname - June 15th, 2017","1","USD","Jun 19th, 2017"
"Booking fee - 1.5% - gxLXmVr - Manual - Nadav - June 12th, 2017","11","USD","Jun 12th, 2017"
"Booking fee - 1.5% - nYrV2Mp - Manual - Manhattan 1 - June 15th, 2017","2","USD","Jun 19th, 2017"
"Booking fee - 0% - MEQmRp5 - Manual - nickname - June 21st, 2017","0","USD","Jul 3rd, 2017"
"Booking fee - 1.5% - B8L7l3J - website - Luxury 123 - June 12th, 2017","1","USD","Jun 19th, 2017"
"Booking fee - 0% - KYZkn6l - Manual - nickname - June 27th, 2017","0","USD","Jun 19th, 2017"
"Booking fee - 1.5% - 8o6vQvj - elads - Liat - July 1st, 2017","2","USD","Jul 3rd, 2017"
Returns a list of all paid invoice items.
HTTP Request
POST /billing/invoice-items/download.csv
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| accountId | --- | Limit to user. | 531968414930a7f09b075800 |
| methodId | --- | Limit to payment method. | 531968414930a7f09b075800 |
| invoiceId | --- | What invoices to download. Can send an array. | 531968414930a7f09b075800 |
At least one of these is required: accountId, methodId or invoiceId.
Response
CSV file with download headers. One CSV file for all items (No separate file for each invoice).
CSV is a spreadsheet of invoice items (fields): description, amount, currency, paidAt
No limit on rows count.
Billing - Payment Methods
Payment method object
{
"_id" : "58bfe8b91e5a1c10007922c7",
"accountId" : "57e2f67cb1261e0f0054cafe",
"method" : "STRIPE",
"payload" : {
"tokenization_method" : null,
"name" : "EXAMPLE",
"last4" : "EXAMPLE",
"funding" : "credit",
"fingerprint" : "EXAMPLE",
"exp_year" : 2016,
"exp_month" : 6,
"dynamic_last4" : null,
"cvc_check" : null,
"customer" : "cus_AFXughdfugEXAMPLE",
"country" : "ISR",
"brand" : "American Express",
"address_zip_check" : null,
"address_zip" : null,
"address_state" : null,
"address_line2" : null,
"address_line1_check" : null,
"address_line1" : null,
"address_country" : null,
"address_city" : null,
"object" : "card",
"id" : "card_19v2pAASsdaEXAMPLE"
},
"last4" : "EXAMPLE",
"brand" : "American Express",
"createdAt" : "2017-03-08T11:19:21.185Z",
"saveForFutureUse" : true,
}
| Attribute | Type | Description |
|---|---|---|
| _id | String | Unique id |
| accountId | ObjectId (String) | Owner |
| method | Enum | Can be any supported payment method (STRIPE, CASH etc.). |
| payload | payload Object |
(see below) |
| saveForFutureUse | Boolean | |
| createdAt | Date | |
| last4 | String | |
| brand | String | Visa, MasterCard, American Express etc. |
The payload object
@See Stripe api docs for description
| Attribute | Type |
|---|---|
| id | String |
| object | String |
| last4 | String |
| brand | String |
| funding | String |
| exp_month | Number |
| exp_year | Number |
| country | String |
| name | String |
| address_line1 | String |
| address_line2 | String |
| address_city | String |
| address_state | String |
| address_zip | String |
| address_country | String |
| cvc_check | String |
| address_line1_check | String |
| address_zip_check | String |
| tokenization_method | String |
| dynamic_last4 | String |
| metadata | Object |
| customer | String |
List all payment methods
{
"count": 1,
"limit": 25,
"skip": 0,
"results": [
{
"_id" : "58bfe8b91e5a1c10007922c7",
"accountId" : "57e2f67cb1261e0f0054cafe",
"method" : "STRIPE",
"payload" : {
"tokenization_method" : null,
"name" : "EXAMPLE",
"last4" : "EXAMPLE",
"funding" : "credit",
"fingerprint" : "EXAMPLE",
"exp_year" : 2016,
"exp_month" : 6,
"dynamic_last4" : null,
"cvc_check" : null,
"customer" : "cus_AFXughdfugEXAMPLE",
"country" : "ISR",
"brand" : "American Express",
"address_zip_check" : null,
"address_zip" : null,
"address_state" : null,
"address_line2" : null,
"address_line1_check" : null,
"address_line1" : null,
"address_country" : null,
"address_city" : null,
"object" : "card",
"id" : "card_19v2pAASsdaEXAMPLE"
},
"last4" : "EXAMPLE",
"brand" : "American Express",
"createdAt" : "2017-03-08T11:19:21.185Z",
"saveForFutureUse" : true,
}
]
}
HTTP Request
GET /billing/payment-methods
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| accountId | null |
Limit to a specific user | 531968414930a7f09b075800 |
| fields | null |
Selection of fields, separated by space | "listings" |
Response
Payment method objects
Add a payment method
HTTP Request
POST /billing/payment-methods
Body Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| method | null |
Payment method enum. | stripe |
| listings | null |
Array of listings ids in string format, that this payment method would be used for. | |
| receiptExtraContent | null |
Text that will be added to each receipt | |
| sendReceiptsByEmail | null |
Whether receipt should be sent out to customer. | |
| stripe | Object |
For payments method of type stripe. |
stripe object
@See Stripe api docs for description
| Parameter | Default | Description | Example |
|---|---|---|---|
| source | --- | Required card token returned from Stripe.js |
Response
Payment method object.
Retrieve a payment method
HTTP Request
GET /billing/payment-methods/:id
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| fields | null |
Selection of fields, separated by space | "listings" |
Response
Payment method object.
Update a payment method
HTTP Request
PUT /billing/payment-methods/:id
Body
| Parameter | Default | Description | Example |
|---|---|---|---|
| isDefault | null |
Whether this payment method is the default. | true |
| listings | null |
Strings of listing ids | 531968414930a7f09b075800 |
| receiptExtraContent | null |
Text that will be added to each receipt | Guesty, Inc. |
| sendReceiptsByEmail | null |
Whether receipt should be sent out to customer. | true |
| stripe | null |
Update to a payment method of type stripe |
stripe object
@See Stripe api docs for description
Body is applied to stripe directly.
Response
The updated payment method object.
Remove a payment method
HTTP Request
DELETE /billing/payment-methods/:id
Response
OK
Websites
The website object
{
"_id": "59a43af221ca870f00f2a58a",
"url": "example",
"title": "TILTER",
"domainName": "",
"pic": "https://cdn.filepicker.io/api/file/gutVyCgTdmcK3uGHCsRI",
"logo": "https://cdn.filepicker.io/api/file/A8dUZqkGRyiMdGp2xeoK",
"maxGuests": 16,
"color": "#6AC1FF",
"accountId": "563e0b6a08a2710e00057b82",
"guestyDomain": "example.guestybookings.com",
"__v": 0,
"companyInfo": {
"name": "example website",
"address": "",
"email": "example@guesty.com",
"phones": [
{
"number": "+972504048705",
"type": "Mobile"
}
]
},
"excludedListings": [],
"includedListings": [
"57e2476e58621d0f003eaac5"
],
"defaultSort": "title",
"sections": [
{
"index": 0,
"name": "About",
"type": "INFO",
"_id": "59a43af221ca870f00f2a58d",
"payload": {
"description": "This is the about description",
"title": "This is the about title"
},
"active": true
},
{
"index": 1,
"name": "Services",
"type": "SERVICES",
"payload": {
"items": [
{
"title": "Bath is a must, otherwise you stink",
"description": "",
"icon": {
"name": "bath",
"src": "assets/images/amenities/bath.svg",
"cleanName": "Bath"
}
},
{
"title": "Don't BBQ after the bath!",
"description": "",
"icon": {
"name": "bbq",
"src": "assets/images/amenities/bbq.svg",
"cleanName": "Bbq"
}
},
{
"title": "You can always break a chair on us if you're pissed!",
"description": "",
"icon": {
"name": "chair",
"src": "assets/images/amenities/chair.svg",
"cleanName": "Chair"
}
}
],
"description": "This is the service description",
"title": "This is the service title"
},
"_id": "59a43af221ca870f00f2a58c",
"active": true
}
],
"bookingType": "INQUIRY",
"social": [
{
"url": "http://facebook.com/guesty",
"type": "FACEBOOK",
"_id": "59afe283fa62f80f00fdd7dd"
}
],
"defaultStatusForNewReservations": "inquiry",
"active": true
}
| Attribute | Type | Description |
|---|---|---|
| _id | String | Unique Id |
| accountId | String | Unique Id |
| active | Boolean | |
| url | String | |
| domainName | String | |
| defaultStatusForNewReservation | Enum | inquiry, reserved |
| maxGuests | Number | Min: 1, Max: 16 |
| title | String | |
| pic | String | |
| logo | String | |
| color | String | |
| social | [social] | see below |
| sections | [sections] | see below |
| defaultSort | Enum | title, accommodates, bedrooms |
| GA | String | |
| includedListings | [Sting]-(ObjectId) | Array of the included listing Ids |
| excludedListings | [Sting]-(ObjectId) | Array of the excluded listing Ids |
| companyInfo | [companyInfo] | see below |
The sections object
| Attribute | Type | Description |
|---|---|---|
| active | Boolean | |
| index | String | Required |
| name | String | Required |
| type | Enum | SERVICE, INFO, CONTACT |
| payload | Object |
The social object
| Attribute | Type | Description |
|---|---|---|
| type | Enum | YOUTUBE, FACEBOOK, INSTAGRAM, TWITTER |
| url | String |
The companyInfo object
| Attribute | Type | Description |
|---|---|---|
| name | String | |
| address | String | |
| phones | [phones] | |
| String |
List websites
[
{
"_id": "59a43af221ca870f00f2a58a",
"url": "example",
"title": "TILTER",
"domainName": "",
"pic": "https://cdn.filepicker.io/api/file/gutVyCgTdmcK3uGHCsRI",
"logo": "https://cdn.filepicker.io/api/file/A8dUZqkGRyiMdGp2xeoK",
"maxGuests": 16,
"color": "#6AC1FF",
"accountId": "563e0b6a08a2710e00057b82",
"guestyDomain": "example.guestybookings.com",
"__v": 0,
"companyInfo": {
"name": "example website",
"address": "",
"email": "example@guesty.com",
"phones": [
{
"number": "+972504048705",
"type": "Mobile"
}
]
},
"excludedListings": [],
"includedListings": [
"57e2476e58621d0f003eaac5"
],
"defaultSort": "title",
"sections": [],
"bookingType": "INQUIRY",
"social": [
{
"url": "http://facebook.com/guesty",
"type": "FACEBOOK",
"_id": "59afe283fa62f80f00fdd7dd"
}
],
"defaultStatusForNewReservations": "inquiry",
"active": true
}
]
HTTP Request
GET /websites/dashboard
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| fields | null |
Selection of fields, separated by space | title createdAt |
| sort | -createdAt |
Field to sort by. Prepend - for DESC. |
createdAt |
| limit | 25 | Pagination, max: 100 | 25 |
| skip | 0 | Pagination | 0 |
Response
List of websites.
Retrieve a website
{
"_id": "59a43af221ca870f00f2a58a",
"url": "example",
"title": "TILTER",
"domainName": "",
"pic": "https://cdn.filepicker.io/api/file/gutVyCgTdmcK3uGHCsRI",
"logo": "https://cdn.filepicker.io/api/file/A8dUZqkGRyiMdGp2xeoK",
"maxGuests": 16,
"color": "#6AC1FF",
"accountId": "563e0b6a08a2710e00057b82",
"guestyDomain": "example.guestybookings.com",
"__v": 0,
"companyInfo": {
"name": "example website",
"address": "",
"email": "example@guesty.com",
"phones": [
{
"number": "+972504048705",
"type": "Mobile"
}
]
},
"excludedListings": [],
"includedListings": [
"57e2476e58621d0f003eaac5"
],
"defaultSort": "title",
"sections": [],
"bookingType": "INQUIRY",
"social": [
{
"url": "http://facebook.com/guesty",
"type": "FACEBOOK",
"_id": "59afe283fa62f80f00fdd7dd"
}
],
"defaultStatusForNewReservations": "inquiry",
"active": true
}
HTTP Request
GET /websites/dashboard/:id
Query Parameters
| Parameter | Default | Description | Example |
|---|---|---|---|
| limit | 10 |
Pagination for invoice items | 10 |
| skip | 0 |
Pagination for invoice items | 0 |
Response
The requested website object
Delete a website
"OK"
HTTP Request
DELETE /websites/dashboard/:id
Response
OK
WebHooks
The Webhooks object
| Attribute | Type | Description |
|---|---|---|
| _id | String (Unique) | |
| url | String | |
| accountId | String (Unique) | |
| events | [Enum] | (See Guesty events) |
Guesty events
- guest.created
- guest.deleted
- guest.updated
- listing.updated
- listing.calendar.updated
- payments.failed
- reservation.messageReceived
- reservation.new
- reservation.updated
- reservation.messageSent
- reservation.reviewed
- task.created
- task.deleted
- task.updated
List all account WebHooks
HTTP Request
GET /webhooks
Authorization
Requires
Response
An Array of WebHooks
[
{
"_id": "595a7fc636f2491000b6b81a",
"accountId": "55b9f9b5393dfe0e004b6c5d",
"url": "https://www.hookurl.com",
"__v": 0,
"events": [
"guest.updated",
"listing.new",
"listing.removed",
"payments.failed",
"reservation.new",
"reservation.updated",
"reservation.reviewed",
"task.created",
"task.updated"
]
}
]
Create a WebHook
HTTP Request
POST /webhooks
Body
| Parameter | Default |
|---|---|
| url | Required |
| accountId | Required |
| events | Required |
Response
Status code of 201 created.
Created WebHook Object, see List all account WebHooks
Retrieve a WebHook
HTTP Request
GET /webhooks/:id
Response
An WebHook Object, see List all account WebHooks
Update a WebHook
HTTP Request
PUT /webhooks/:id
- id - is the WebHook _id you got when create a WebHook, see Create a WebHooks
Body
- url
- events
Response
Status code 204 if success
Delete a WebHook
HTTP Request
DELETE /webhooks/:id
Response
Status code 204 if success
Webhook Structure
guest.created
{
"guest" : {
"__v" : 0,
"fullName" : "Example Guest",
"firstName" : "Example",
"lastName" : "Guest",
"email" : "example@email.com",
"accountId" : "563e0b6a08a2710e00057b82",
"_id" : "59ccd0620de3881000b0f2e1",
"paymentMethodIds" : [],
"communicationMethods" : [
"email"
],
"airbnb" : {
"id" : 1506594914760
},
"phones" : [],
"emails" : [
"example@email.com"
],
"pictures" : [],
"verifications" : []
},
"by" : "Someone from my team",
"event" : "guest.created"
}
Body
| Attribute | Type | Description |
|---|---|---|
| guest | Object | guest object - see The guest object |
| by | String | |
| event | String | guest.created |
guest.deleted
{
"guest":{
"_id" : "59ccd0620de3881000b0f2e1",
"fullName":"Example Guest",
"firstName":"Example",
"lastName":"Guest",
"email":"example@email.com",
"accountId":"563e0b6a08a2710e00057b82",
"__v":0,