Responses
\n401 Unauthorised
\nIf the API key is not recognised in any API calls, the response will be 401 Unauthorised
\n200 OK
\nFor GET endpoints: If the request body is formatted correctly, the response will be a 200 OK.
\n201 Created
\nFor most POST endpoints, the response will be 201 with the ID of the entity created
\n202 Accepted
\nFor the calendar update endpoint: If the request body is formatted correctly, the response will be a 202 Accepted. Along with a request ID as a JSON response.
\nRate limiting
\nThe API is designed to provide a list of bookings/availability as a \"snapshot\" and then webhooks should be used to get up-to-date information on changes in the system.
\nAll calls to the Uplisting API are subject to rate limiting. If a partner exceeds the rate limits, a 429 Too Many Requests response is returned. We recommend to stagger requests througout a longer time frame to avoid hitting 429s.
\nWe allow up to 5 requests per second per IP address and no more than 100 requests per minute per IP address and no more than 15 requests per min per property.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"1320372","collectionId":"41f0ddab-68ae-4900-b800-d68c83408684","publishedId":"SWTBfdW6","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"00996E"},"publishDate":"2020-01-30T14:20:14.000Z"},"item":[{"name":"Webhook notifications","item":[{"name":"Webhook - Registering Hooks","id":"4db91c6c-d0b1-485d-a5c7-3d9bec7ff1df","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Basic MATwZDQ0YjEtMTRmZS00MmJhLTg1OGEtNmM4MDBmNjBlMTNi","type":"text"}],"body":{"mode":"raw","raw":"{\n \"target_url\": \"https://hooks.zapier.com/hooks/catch/11700/osfupzi/\",\n \"event\": \"booking_created\"\n}","options":{"raw":{"language":"json"}}},"url":"https://connect.uplisting.io/hooks","description":"To receive a push notification when a booking is created/updated/removed, or a property is created/updated/removed, you need to register a hook that we will the POST with a payload when one of the above events happen.
\nbooking_created
Triggers for each new booking imported from a booking site, or created on Uplisting.
booking_updated
Triggers when changes are made to any booking.
booking_removed
Triggers when a booking is cancelled or removed.
When a booking is created, we will POST to that target_url with a payload of:
{\n id: 1,\n accommodation_management_fee: 20.0,\n accomodation_total: 362.45,\n arrival_time: \"15:00:00\",\n automated_messages_enabled: true,\n automated_reviews_enabled: false,\n booked_at: \"2021-11-26T11:19:59Z\",\n channel: \"airbnb_official\",\n check_in: \"2021-12-03\",\n check_out: \"2021-12-05\",\n cleaning_fee: 40.0,\n cleaning_management_fee: 4.0,\n commission: 14.0,\n currency: \"GBP\",\n departure_time: \"11:00:00\",\n direct: false,\n external_reservation_id: \"ABC2DEF3YZ\",\n guest_email: \"jon.snow@castleblack.com\",\n guest_name: \"Jon Snow\",\n guest_phone: \"+44797978889991\",\n lock_code: \"1234\",\n manually_moved: false,\n multi_unit_id: null,\n multi_unit_name: null,\n note: \"Bringing the dragon\",\n number_of_guests: 3,\n number_of_nights: 7,\n other_charges: null,\n preferred_guest_name: \"King of the North\",\n property_id: 2,\n property_name: \"Mi Casa\",\n source: null,\n status: \"confirmed\",\n timestamp: \"2021-11-26T11:20:00Z\",\n total_management_fee: 48,\n total_payout: 388\n}\n\nOther booking-related hooks you can register are for booking_updated and booking_removed. Follow the same approach as above to register a target URL for each event.
For booking_updated, the payload will be as above.
For booking_removed when a booking is cancelled the payload would also be as above with an additional attribute of reason.
For bookings that are deleted from the Uplisting calendar the payload is a more reduced one, e.g:
\n{\n id: 163760,\n arrival_time: \"15:00:00\",\n automated_messages_enabled: true,\n automated_reviews_enabled: false,\n booked_at: \"2021-11-26T12:51:01+00:00\",\n channel: \"uplisting\",\n check_in: \"2021-12-02\",\n check_out: \"2021-12-03\",\n currency: \"USD\",\n departure_time: \"11:00:00\",\n direct: false,\n guest_name: \"Jon Snow\",\n lock_code: \"1234\",\n manually_moved: false,\n number_of_nights: 1,\n preferred_guest_name: \"King of the North\",\n property_id: 11456,\n property_name: \"Mi Casa\",\n reason: \"destroyed\",\n timestamp: \"2021-11-26T11:20:00Z\"\n}\n\nField
\nchannel
\nDescription
\n\"airbnb\", \"google\", \"booking_dot_com\", \"uplisting\", \"homeaway\"
Field
\nreason
\nDescription
\nReason for the booking modification:
\n\"cancelled\"
\"checked_in\"
\"checked_out\"
\"confirmed\"
\"externally_removed\"
\"needs_check_in\"
\"needs_check_out\"
\"remove_pending\"
\"removed_as_unpaid\"
property_created
property_updated
property_removed
The payload for property related webhooks is:
\n{\n id: property.id,\n name: \"Mi Casa\",\n nickname: \"Su Casa\",\n timestamp: \"2021-11-26T11:20:00Z\",\n time_zone: \"Europe/London\"\n}\n\nProperty webhooks are sent when attributes on the property change - e.g. the name or nickname - as well as when associated amenities or address changes. The best approach to getting updated property information is to make an API request to GET /properties/:id for the property ID that is included in the payload.
In order to make sure your system is notified about changes webhooks are retried unless we receive a 200 OK HTTP response. We use an exponential backoff logic and will retry to deliver the webhook for 21 times (in total for 8 days 8 hours post timestamp time).
To handle order issues we recommend to use the provided timestamp attribute, which represents the timestamp of the event in UTC timezone and ISO8601 format.
You should be discarding any webhooks with an earlier timestamp to prevent writing stale data.
For example:
\nThere's a booking with guest_name set to \"Jon\".
guest_name is updated to \"Sam\" at 2022-03-24T11:03:00Z.
A booking_updated webhook timestamp: 2022-03-24T11:03:00Z is attempted to deliver changes, however we don't get a successful response. We will retry to deliver the webhook at a later time.
The same booking guest_name changes to \"Ben\" at 2022-03-24T11:05:00Z.
A booking_updated webhook with timestamp: 2022-03-24T11:05:00Z is atttempted to deliver changes and we get a successful response.
The failed webhook with timestamp: 2022-03-24T11:03:00Z retries and successfully delivers guest_name changed to \"Sam\" payload.
If handled incorrectly the guest name will be set to \"Sam\" as that was the value for the guest_name attribute in the last webhook.
A better approach would be to log the timestamp of the last webhook for the booking (2022-03-24T11:05:00Z) and don't process webhooks with an earlier timestamp (2022-03-24T11:05:00Z).
Due to the nature of HTTP requests you might receive a webhook more than once. While that's generally not an issue for _updated webhooks, _created or _removed webhook can fail as you would be trying to:
a) create a booking/property with the same Uplisting ID more than once
b) remove a booking/property for an Uplisting ID that is no longer present in your database.
We recommend you to handle these changes in an idempotent way. Your system shouldn't fail at processing same webhook more than once.
If an endpoint fails to respond to 5 different events consecutively, our system will mark it as disabled. From that point forward, no further events will be posted to this endpoint until further notice. Please ensure your endpoint is reliable and responds within the expected timeframe to avoid disruption.
\nYour service is expected to process the webhook and send a response within 5 seconds of receiving it. If your service doesn't respond within this timeframe, the webhook call will be marked as failed. Our system will then attempt to redeliver the webhook according to our retry mechanism outlined above. Please ensure your service is capable of processing incoming webhooks in a timely manner to avoid unnecessary retries and potential marking of your endpoint as disabled. We recommend building your service to acknowledge the webhook receipt immediately, and then process the payload asynchronously to avoid any timeouts.
\n","urlObject":{"protocol":"https","path":["hooks"],"host":["connect","uplisting","io"],"query":[],"variable":[]}},"response":[{"id":"93147142-a436-4ccd-a324-d00ac901d874","name":"Webhook - Registering Hooks","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Basic MATwZDQ0YjEtMTRmZS00MmJhLTg1OGEtNmM4MDBmNjBlMTNi","type":"text"}],"body":{"mode":"raw","raw":"{\n \"target_url\": \"https://hooks.zapier.com/hooks/catch/11700/osfupzi/\",\n \"event\": \"booking_created\"\n}","options":{"raw":{"language":"json"}}},"url":"https://connect.uplisting.io/hooks"},"status":"Created","code":201,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"Cowboy"},{"key":"Date","value":"Tue, 09 Jun 2020 23:07:18 GMT"},{"key":"Connection","value":"keep-alive"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-Xss-Protection","value":"1; mode=block"},{"key":"Content-Security-Policy","value":"form-action 'self'; frame-ancestors 'self'; base-uri 'self'; default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self' https: data:; style-src 'self' 'unsafe-inline' https:; font-src 'self'; object-src 'none'; plugin-types application/pdf; child-src 'self'; frame-src 'self'; media-src 'self'"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Vary","value":"Origin"},{"key":"Content-Length","value":"11"},{"key":"Via","value":"1.1 vegur"}],"cookie":[],"responseTime":null,"body":"{\n \"id\": 1269\n}"}],"_postman_id":"4db91c6c-d0b1-485d-a5c7-3d9bec7ff1df"},{"name":"Webhook - Removing hooks","id":"ee97c3f6-0ee7-4c6a-b0f1-64599cafc637","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[{"key":"Content-Type","type":"text","value":"application/json"},{"key":"Authorization","type":"text","value":"Basic Mat4N2QfZTAtMzA3My00NjBmLTllMTMtNTE5NDY2NDE4Zjdm"}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"https://connect.uplisting.io/hooks/1837","description":"If you wish to remove a hook (e.g. unsubscribe from further events) then send DELETE to https://connect.uplisting.io/hooks/:id where id is the ID you got back when first registering the hook.
Retrieving details of registered webhooks
\nTo retrieve the details for all webhooks registered for a user, you should send a GET request to the endpoint above.
\nThe payload will be a list of webhooks for the partner account in JSON API format.
\nFor more info on JSON API format, visit https://jsonapi.org.
\n","urlObject":{"protocol":"https","path":["hooks"],"host":["connect","uplisting","io"],"query":[],"variable":[]}},"response":[{"id":"47a50811-501d-4138-a1e6-29af43d600a0","name":"Hooks Index","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Basic YzhlZGU3NDctNDUzNi00MGVmLWJkYWMtMzZjZjVlMGQxZDVk","type":"text"}],"url":"https://connect.uplisting.io/hooks"},"status":"Unauthorized","code":401,"_postman_previewlanguage":"json","header":[{"key":"Connection","value":"keep-alive"},{"key":"Server","value":"nginx"},{"key":"Date","value":"Fri, 02 Jul 2021 16:55:30 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"41"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-Xss-Protection","value":"1; mode=block"},{"key":"Content-Security-Policy","value":"form-action 'self'; frame-ancestors 'self'; base-uri 'self'; default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self' https: data:; style-src 'self' 'unsafe-inline' https:; font-src 'self'; object-src 'none'; plugin-types application/pdf; child-src 'self'; frame-src 'self'; media-src 'self'"},{"key":"Vary","value":"Origin"},{"key":"Via","value":"1.1 vegur, 1.1 vegur"}],"cookie":[],"responseTime":null,"body":"{\n \"data\": [\n {\n \"id\": \"305\",\n \"type\": \"webhooks\",\n \"attributes\": {\n \"target_url\": \"https://uplisting.eu.ngrok.io/hook/booking_created_2\",\n \"event\": \"booking_created\",\n \"created_at\": \"2020-12-16T11:35:58Z\",\n \"updated_at\": \"2020-12-16T11:35:58Z\"\n }\n },\n {\n \"id\": \"319\",\n \"type\": \"webhooks\",\n \"attributes\": {\n \"target_url\": \"https://uplisting.eu.ngrok.io/hook/booking_created_4\",\n \"event\": \"booking_created\",\n \"created_at\": \"2020-12-16T14:40:12Z\",\n \"updated_at\": \"2020-12-16T14:40:12Z\"\n }\n }\n ]\n}"}],"_postman_id":"059fb66a-d36b-4ba1-a41c-e6bbf7cb9c7d"}],"id":"f261ba89-e4cb-4375-aa4c-8e7d4764e568","_postman_id":"f261ba89-e4cb-4375-aa4c-8e7d4764e568","description":""},{"name":"v2","item":[{"name":"Custom booking attributes","id":"e1355152-494e-4af2-8915-8ddeebdf7884","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Basic ODM1ZjBjMTItNWM3Mi00ZDA2LWFkY2MtYzA3MjYwYTBjMDNh","type":"text"},{"key":"X-Uplisting-Client-Id","value":"8a818455-dbfb-4fc2-951b-6ff7e8b546ae","type":"text"}],"url":"https://connect.uplisting.io/v2/custom_booking_attributes","description":"Listing booking attributes that can be changed
\nThere are only certain attributes that can be changed on any specific booking and those are listed under this endpoint.
\nThe use case here is to retrieve the list of attributes for a specific account using a host's API key. These can then be mapped to attributes on a partner's side and used with the `PATCH /v2/bookings/:id` endpoint to make changes to the booking.
\nThese values are then used in Uplisting in automated messaging by replacing special tags used in messaging templates.
\nNOTE: This endpoint requires a partner client ID in the header under the X-Uplisting-Client-ID header. Contact Uplisting if you don't have a partner specific client ID on partner@uplisting.io.
Any attribute listed in the custom booking attributes endpoint can be updated via this endpoint and values set against a specific booking.
\nAttribute values can be anything that is represented by a string, e.g.
\n{\n \"data\": {\n \"attributes\": {\n \"lock_code\": 1234567\n }\n }\n}\n\nThese attributes can then be used by the host in automated message tags.
\nValues are accepted with an HTTP 201 response.
\nNOTE: This endpoint requires a partner client ID in the header under the X-Uplisting-Client-ID header. Contact Uplisting if you don't have a partner specific client ID.
Creates a new custom booking attribute that can be used to store additional metadata for bookings.
\nEach attribute is tied to the partner API client that created it and must follow specific naming conventions.
\nMaximum: 15 custom booking attributes per partner per account.
\nNamespace Enforcement:
Attribute names must be namespaced (e.g., partnername_attribute_name).
Naming Convention:
Only underscore-style (snake_case) names are allowed.
⚠️ Note: Partner clients must have their custom_booking_attribute_prefix set before they can create custom booking attributes. (Please contact our Partner team on partner@uplisting.io to have that configured)
Values are accepted with an HTTP 201 response.
\nNOTE: This endpoint requires a partner client ID in the header under the X-Uplisting-Client-ID header. Contact Uplisting if you don't have a partner specific client ID.
Endpoint allows creating confirmed bookings and accepts the following attributes:
\ncheck_in - required, date in ISO8601 format.check_out - required, date in ISO8601 format, date must be after `check_in` date.property ID - required.Optional attributes:
\nguest_name - optional, guest name shown on the booking calendar and used for automated messaging.guest_email - optional, a valid email is required for any scheduled messages to be delivered to the guest.guest_phone - optional.number_of_guests - optional, used for price calculation.NOTE: This endpoint requires a partner client ID in the header under the X-Uplisting-Client-ID header. Contact Uplisting if you don't have a partner specific client ID.
Initially, you need to verify that your API key is correct and that you are using the correct authentication header.
To do so, GET the following URL: https://connect.uplisting.io/users/me with an authorisation header that is your API key encoded with Base64 with application/json content-type.
For example, in Ruby, these are the headers you need to pass.
\nHash[\"HTTP_AUTHORIZATION\" => \"Basic #{Base64.encode64(api_key)}\", \"CONTENT_TYPE\" => \"application/json\"]\n\nIf successful, you should get back the name of your account and a unique ID for the user.
\n{\n \"name\": \"Uplisting\",\n \"uid\": \"7005ddf20990ceaac970415da5eb86cd29c4c7323f527c66f18978f8e36edd7a\"\n}\n\nThis proves that you have the correct authorisation header, which should be used for all future communication.
\nIf you receive an error that states \"Your API key does not appear to be valid\" please first check you have Base64 encoded the key. Otherwise please reach out to partner@uplisting.io for further assistance including the email address of the Account owner.
\n","urlObject":{"protocol":"https","path":["users","me"],"host":["connect","uplisting","io"],"query":[],"variable":[]}},"response":[{"id":"0791449d-cd85-4319-aec0-7ecc54a32b39","name":"Verify API key","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Basic MAIwZ44FFQ0YjEtMTRmZS00MmJhLTg1OGEtNmM4MDBmNjBlMTNi","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"url":"https://connect.uplisting.io/users/me"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"Cowboy"},{"key":"Date","value":"Tue, 09 Jun 2020 22:54:16 GMT"},{"key":"Connection","value":"keep-alive"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"X-Xss-Protection","value":"1; mode=block"},{"key":"Content-Security-Policy","value":"form-action 'self'; frame-ancestors 'self'; base-uri 'self'; default-src 'none'; script-src 'self'; connect-src 'self'; img-src 'self' https: data:; style-src 'self' 'unsafe-inline' https:; font-src 'self'; object-src 'none'; plugin-types application/pdf; child-src 'self'; frame-src 'self'; media-src 'self'"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Vary","value":"Origin"},{"key":"Content-Length","value":"15"},{"key":"Via","value":"1.1 vegur"}],"cookie":[],"responseTime":null,"body":"{\n \"name\": \"Uplisting\",\n \"uid\": \"7005ddf20990ceaac970415da5eb86cd29c4c7323f527c66f18978f8e36edd7a\"\n}"}],"_postman_id":"e3a6c410-8945-4192-bfd9-e2a4f8fd4514"},{"name":"Properties","id":"9a49afe4-9eb4-4b63-87ba-81b44dd33fe9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"Authorization","value":"Basic YzhlZGU3NDctNDUzNi00MGVmLWJkYWMtMzZjZjVlMGQxZDVk","description":"Base64 encoded API key
\n","type":"text"}],"url":"https://connect.uplisting.io/properties","description":"Retrieving details for all properties
\nTo retrieve the details for all properties on an Uplisting account, you should send a GET request to the endpoint above.
\nThe payload will be a list of properties for the partner account in JSON API format. It will also include the property address, photos, multi-units, fees, taxes, discounts, suitabilities and amenities in the included data.
\nFor a full example of the JSON response, see the property endpoint. This endpoint will return an array of properties with the same format as a single property
\nFor more info on JSON API format, visit https://jsonapi.org.
\nProperties have relationships which include address, photos, multi-units, fees, taxes, discounts, suitabilities, policies, channel commissions and amenities types. Each individual relationship references the relevant resource in the included section of the API response, per the JSON API format.
\nOur example property's address relationship is provided as follows:
\n\"address\": {\n \"data\": {\n \"id\": \"15111\",\n \"type\": \"addresses\"\n }\n}\n\nAnd the included data has the relevant address.
\n{\n \"id\": \"15111\",\n \"type\": \"addresses\",\n \"attributes\": {\n \"street\": \"3503 B Street\",\n \"suite\": null,\n \"city\": \"Philadelphia\",\n \"state\": \"PA\",\n \"zip_code\": \"19134\",\n \"country\": \"United States\",\n \"latitude\": 40.003384,\n \"longitude\": -75.123993\n }\n},\n\nOur example of channel commissions relationship is provided as follows:
\n\"channel_commissions\": {\n \"data\": [\n {\n \"id\": \"7775\",\n \"type\": \"channel_commissions\"\n },\n {\n \"id\": \"7776\",\n \"type\": \"channel_commissions\"\n },\n {\n \"id\": \"7777\",\n \"type\": \"channel_commissions\"\n },\n {\n \"id\": \"7778\",\n \"type\": \"channel_commissions\"\n },\n {\n \"id\": \"7779\",\n \"type\": \"channel_commissions\"\n }\n ]\n}\n\nAnd the included data has the relevant channel commissions.
\n[\n {\n \"id\": \"7775\",\n \"type\": \"channel_commissions\",\n \"attributes\": {\n \"channel\": \"airbnb_official\",\n \"amount\": 18.34\n }\n },\n {\n \"id\": \"7776\",\n \"type\": \"channel_commissions\",\n \"attributes\": {\n \"channel\": \"booking_dot_com\",\n \"amount\": 15.0\n }\n },\n {\n \"id\": \"7777\",\n \"type\": \"channel_commissions\",\n \"attributes\": {\n \"channel\": \"home_away\",\n \"amount\": 8.0\n }\n },\n {\n \"id\": \"7778\",\n \"type\": \"channel_commissions\",\n \"attributes\": {\n \"channel\": \"google\",\n \"amount\": 6.0\n }\n },\n {\n \"id\": \"7779\",\n \"type\": \"channel_commissions\",\n \"attributes\": {\n \"channel\": \"direct\",\n \"amount\": 0.0\n }\n }\n]\n\nFor example our a property's photo relationship is provided as follows:
\n\"photos\": {\n \"data\": [\n {\n \"id\": \"159361\",\n \"type\": \"photos\"\n }\n ]\n}\n\nAnd the included data has the relevant photo.
\n{\n \"id\": \"159361\",\n \"type\": \"photos\",\n \"attributes\": {\n \"url\": \"https://cdn.filestackcontent.com/yEswEYOzRaiOBsk90s3w\",\n \"order\": 1,\n \"created_at\": \"2020-01-16T21:55:50Z\",\n \"updated_at\": \"2020-01-16T21:55:50Z\"\n }\n},\n\nIf a property has associated multi-units, these will be included in the JSON API response.
\nFor example:
\n\"multi_units\": {\n \"data\": [\n {\n \"id\": \"68\",\n \"type\": \"multi_units\"\n },\n {\n \"id\": \"69\",\n \"type\": \"multi_units\"\n }\n ]\n}\n\nAnd the included data has the relevant multi_unit:
\n{\n \"id\": \"68\",\n \"type\": \"multi_units\",\n \"attributes\": {\n \"name\": \"5G\"\n }\n}\n\nAll taxes for a property are included, even if those taxes are zero.
\nThe taxes have a type of fixed for a specific amount and percentage for percentages.
They also have a field called per which indicates whether the tax applies per booking (e.g. for the whole stay), per night (e.g. for each night of the stay) or per person_per_night (e.g. per person for each night of the stay).
The amount field indicates the fixed amount, or the percentage amount to apply.
For example:
\n\"taxes\": {\n \"data\": [\n {\n \"id\": \"11033-per_booking_amount\",\n \"type\": \"property_taxes\"\n },\n {\n \"id\": \"11033-per_booking_percentage\",\n \"type\": \"property_taxes\"\n },\n {\n \"id\": \"11033-per_night\",\n \"type\": \"property_taxes\"\n },\n {\n \"id\": \"11033-per_person_per_night\",\n \"type\": \"property_taxes\"\n }\n ]\n}\n\nAnd the included taxes have the relevant data:
\n{\n \"id\": \"11033-per_booking_percentage\",\n \"type\": \"property_taxes\",\n \"attributes\": {\n \"name\": \"Per booking percentage\",\n \"label\": \"per_booking_percentage\",\n \"type\": \"percentage\",\n \"per\": \"booking\",\n \"amount\": 25.25\n }\n}\n\nAll fees - e.g. cleaning fee and/or extra guest charge - for a property are included, if they are setup.
\nThe fees have a field of enabled which indicates if they should be applied.
They also have a field called amount that indicates the actual fee that should be applied.
There's a field named guests_included that indicates, for the extra guest charge fee, how many guests should be included before the fee applies. For example, guests_included 2 means that the guest fee only applies for guests 3 and 4 (for a booking with 4 guests).
For example:
\n\"fees\": {\n \"data\": [\n {\n \"id\": \"11033-cleaning_fee\",\n \"type\": \"property_fees\"\n },\n {\n \"id\": \"11033-extra_guest_charge\",\n \"type\": \"property_fees\"\n }\n ]\n},\n\nAnd the included fees have the relevant data:
\n{\n \"id\": \"11033-cleaning_fee\",\n \"type\": \"property_fees\",\n \"attributes\": {\n \"name\": \"Cleaning fee\",\n \"label\": \"cleaning_fee\",\n \"enabled\": true,\n \"guests_included\": null,\n \"amount\": 100.0\n }\n},\n\nAll discounts for a property are included, even if those discounts are zero.
\nThe discounts have a type of percentage for percentages. (The only type currently supported).
They also have a field called days which indicates how many days the discount applies for (e.g. 7 for a week long stay or 28 for a monthly long stay)
The amount field indicates the percentage amount to apply.
For example:
\n\"discounts\": {\n \"data\": [\n {\n \"id\": \"11033-weekly\",\n \"type\": \"property_discounts\"\n },\n {\n \"id\": \"11033-monthly\",\n \"type\": \"property_discounts\"\n }\n ]\n}\n\nAnd the included discounts have the relevant data:
\n{\n \"id\": \"11033-weekly\",\n \"type\": \"property_discounts\",\n \"attributes\": {\n \"name\": \"Weekly discount\",\n \"label\": \"weekly\",\n \"type\": \"percentage\",\n \"days\": 7,\n \"amount\": 5.0\n }\n}\n\nThis section indicates whether a property is suitable for pets, children, events or smoking.
Each property will have this section:
\n\"suitability\": {\n \"data\": {\n \"id\": \"3428\",\n \"type\": \"suitabilities\"\n }\n}\n\nAnd the included data:
\n{\n \"id\": \"3428\",\n \"type\": \"suitabilities\",\n \"attributes\": {\n \"children\": true,\n \"pets\": false,\n \"events\": false,\n \"smoking\": false\n }\n}\n\nThis section indicates what cancellation policy a property has.
\nEach property will have this section:
\n\"policy\": {\n \"data\": {\n \"id\": \"1234\",\n \"type\": \"policies\"\n }\n}\n\nAnd the included data:
\n{\n \"id\": \"3428\",\n \"type\": \"policies\",\n \"attributes\": {\n \"type\": \"Strict cancellation policy\",\n \"description\": \"Cancel any time before check-in and no refund is provided\"\n }\n}\n\nThis section indicates whether the Uplisting Protect (security deposit) feature is turned on for the property.
\nEach property will have this section if Uplisting Protect has been enabled for the account.
\n\"protect_security_deposit_setting\": {\n \"data\": {\n \"id\": \"1234\",\n \"type\": \"protect_security_deposit_settings\"\n }\n}\n\nAnd the included data:
\n{\n \"id\": \"3428\",\n \"type\": \"protect_security_deposit_settings\",\n \"attributes\": {\n \"amount\": 200.0,\n \"enabled\": true\n }\n}\n\nThe Properties Index endpoint contains amenities for each property. The full list of amenities Uplisting supports are listed below.
\nIn our example the amenity relationship is provided as:
\n\"amenities\": {\n \"data\": [\n {\n \"id\": \"1\",\n \"type\": \"amenities\"\n }\n ]\n}\n\nAnd the included data has the relevant amenity:
\n{\n \"id\": \"1\",\n \"type\": \"amenities\",\n attributes\": {\n \"name\": \"Oven\",\n \"group\": \"Kitchen & Dining\"\n }\n}\n\n| *Amenity Name* | *Amenity Group* |\n-----------------------------------------------------\n| Satellite / Cable | Entertainment |\n| Games | Entertainment |\n| Foosball | Entertainment |\n| DVD Player | Entertainment |\n| Books | Entertainment |\n| Ping Pong Table | Entertainment |\n| Pool Table | Entertainment |\n| Game Room | Entertainment |\n| Music Library | Entertainment |\n| Video Library | Entertainment |\n| Television | Entertainment |\n| Video Games | Entertainment |\n| Toys | Entertainment |\n| Stereo | Entertainment |\n| Oven | Kitchen & Dining |\n| Microwave | Kitchen & Dining |\n| Toaster | Kitchen & Dining |\n| Coffee Maker | Kitchen & Dining |\n| Dishes & Utensils | Kitchen & Dining |\n| Dishwasher | Kitchen & Dining |\n| Kitchen | Kitchen & Dining |\n| Kitchenette | Kitchen & Dining |\n| Pantry Items | Kitchen & Dining |\n| Refrigerator | Kitchen & Dining |\n| Stove | Kitchen & Dining |\n| Deck / Patio | Outdoor Features |\n| Golf | Outdoor Features |\n| Lanai / Gazebo | Outdoor Features |\n| Lawn / Garden | Outdoor Features |\n| Outdoor Grill | Outdoor Features |\n| Ski & Snowboard | Outdoor Features |\n| Tennis | Outdoor Features |\n| Water Sports Gear | Outdoor Features |\n| Balcony | Outdoor Features |\n| Kayak / Canoe | Outdoor Features |\n| Boat | Outdoor Features |\n| Private Pool | Pool & Spa Facilities |\n| Sauna | Pool & Spa Facilities |\n| Indoor Pool | Pool & Spa Facilities |\n| Heated Pool | Pool & Spa Facilities |\n| Communal Pool | Pool & Spa Facilities |\n| Jacuzzi | Pool & Spa Facilities |\n| Spa Whirlpool | Pool & Spa Facilities |\n| Whirlpool | Pool & Spa Facilities |\n| Hot Tub | Pool & Spa Facilities |\n| Air Conditioning | Popular Amenities |\n| Fitness Room / Equipment | Popular Amenities |\n| Fax | Popular Amenities |\n| Internet | Popular Amenities |\n| Fireplace | Popular Amenities |\n| Fireplace guards | Popular Amenities |\n| Wood Stove | Popular Amenities |\n| Garage | Popular Amenities |\n| Elevator | Popular Amenities |\n| Living Room | Popular Amenities |\n| Telephone | Popular Amenities |\n| Iron & Board | Popular Amenities |\n| Hair Dryer | Popular Amenities |\n| Paid parking on premises | Popular Amenities |\n| Paid parking off premises | Popular Amenities |\n| Free street parking | Popular Amenities |\n| Free parking on premises | Popular Amenities |\n| Parking | Popular Amenities |\n| Towels Provided | Popular Amenities |\n| Linens Provided | Popular Amenities |\n| Clothes Dryer | Popular Amenities |\n| Washing Machine | Popular Amenities |\n| Heating | Popular Amenities |\n\nBase64 encoded API key
\n","type":"text"}],"url":"https://connect.uplisting.io/properties/:id","description":"Retrieving details for a single property
\nTo retrieve the details for a property on an Uplisting account, you should send a GET request to the endpoint above.
\nThe payload will be a single property for the partner account in JSON API format. It will also include the property's address, photos, multi-unit, fees, taxes, suitabilities, channel commissions and amenities in the included data.
\nFor more info on JSON API format, visit https://jsonapi.org.
\nProperties have relationships which include address, photos, multi-unit, fees, taxes, suitabilities and amenities types. Each individual relationship references the relevant resource in the included section of the API response, per the JSON API format.
\nFor a full breakdown, review the documentation for the GET /properties endpoint
Retrieving availability for properties
\nTo retrieve the availability of properties on an Uplisting account, you should send a GET request to the endpoint above.
\nThe payload will be a list of properties that meet the search criteria entered in the query string, in JSON API format. It will also include the property addresses, photos and amenities in the included data. (for a fuller explanation, see the properties endpoint)
\nSearch criteria
\nYou can choose to search by any, or all, of these criteria via the query string on the request.
\ncheck_in - the date of check in.check_out - the date of check out (note this is the morning of check out)number_of_guests - the number of guests for the bookingmax_price - the maximum price allowed for the bookingmin_price - the minimum price expected for a bookingcity - scope the properties by a specific city locationBase64 encoded API key
\n","key":"Authorization","type":"text","value":"Basic YzhlZGU3NDctNDUzNi00MGVmLWJkYWMtMzZjZjVlMGQxZDVk"}],"url":"https://connect.uplisting.io/bookings/:listing_id?from=2020-12-10&to=2020-12-20","description":"To retrieve the bookings for a property, you should GET the above endpoint.
\nThe response is limited to a maximum of 50 bookings at a time but is paginated so more bookings can be retrieved, as required.
\nDate range options
\nfrom or to and get a year from today (UTC based)https://connect.uplisting.io/bookings/:listing_idfrom only to get 12 months worth of data from that pointhttps://connect.uplisting.io/bookings/:listing_id?from=2020-02-01from and to and get paginated bookings within that date rangehttps://connect.uplisting.io/bookings/:listing_id?from=2020-02-01&to=2021-12-01Pagination options
\npage=X to get a 0-based page of results.per_page=X to retrieve less than the default of 50 in each pagemeta information included in the response that tells you total bookings and total_pages so you can paginate through as required.Booking statuses
Bookings can have the following statuses.
confirmed [all bookings are in a confirmed state until one of the below statuses takes affect]checked_in [a confirmed booking which has been marked as checked-in by the host]checked_out [a confirmed booking which has been marked as checked-out by the host]needs_check_in [a confirmed booking which is waiting to be checked-in by the host. The host may not mark this booking as checked-in]needs_check_out [a confirmed booking which is waiting to be checked-out by the host. The host may not mark this booking as checked-out]cancelled [a booking which is now cancelled, ie. the booking is not longer active]The response is the same payload as for a booking_updated webhook repeated for each booking retrieved. All bookings are available, including cancelled bookings. See the example for more info.
Base64 encoded API key
\n","type":"text"}],"url":"https://connect.uplisting.io/calendar/:listing_id?from=2020-12-10&to=2020-12-20","description":"To retrieve the calendar for a property, you should GET to the above endpoint.
\nThe response is limited to 12 months at one time.
\nDate range options
\nSpecify neither from or to and get a year from today
https://connect.uplisting.io/calendar/:listing_id
Specify a from only to get 12 months worth of data from that point
https://connect.uplisting.io/calendar/:listing_id?from=2020-02-01
Specify from and to and get up up to 12 months worth of data within that date range
https://connect.uplisting.io/calendar/:listing_id?from=2020-02-01&to=2021-12-01
Included in the response is the price, and restrictions such as availability, minimum length of stay and closed for arrival, e.g:
\n\"available\": true,\n\"available_count: 1,\n\"date\": \"2020-12-10\",\n\"day_rate\": 150,\n\"minimum_length_of_stay\": 5,\n\"maximum_nights_available\": 15,\n\"closed_for_arrival\": false,\n\"closed_for_departure\": false\n\navailable: this is a simple true/false as to whether the property is available on the date listed.
available_count: this indicates how many properties are available on that date. It will be 1 unless a property has multi-units attached to it. For multi-units, it indicates how many units are available on that date.
date: the day the details are for
day_rate: the price (in the property's currency)
minimum_length_of_stay: The minimum length for any booking that starts on this date.
maximum_nights_available: How many nights can be booking in a contiguous block. Note that this may actually be less than the minimum_length_of_stay because the MLOS is a property-specific restriction and is not date-specific.
closed_for_arrival: true/false as to whether a booking can check-in on this date.
closed_for_departure: true/false as to whether a booking can check-out on this date.
Base64 encoded API key
\n","key":"Authorization","type":"text","value":"Basic YzhlZGU3NDctNDUzNi00MGVmLWJkYWMtMzZjZjVlMGQxZDVk"}],"body":{"mode":"raw","raw":"{\n\t\"notification_url\": \"https://yourdomain.eu.ngrok.io/notification\",\n\t\"calendar\": {\n\t\t\"days\": [\n {\n \"available\": true,\n \"date\": \"2020-12-13\",\n \"day_rate\": 170.0,\n \"minimum_length_of_stay\": 2,\n \"closed_for_arrival\": false,\n \"closed_for_departure\": true\n },\n {\n \"available\": false,\n \"from\": \"2021-01-01\",\n \"to\": \"2021-02-01\"\n }\n\t\t]\n\t}\n}"},"url":"https://connect.uplisting.io/calendar/:listing_id","description":"Uplisting provides calendar-based endpoints for updating rates, availability and minimum length of stay for a specific date range. Any updates made via the API are broadcast to all channels the property is connected to on Uplisting.
\nNotification
\nThis POST results in an asynchronous response to the server listed at the notification_url with a payload indicating success/failure of the changes requested and including that request ID so the response can be matched to the initial POST.
\nThe notification URL is not required. If no URL is provided, no notifications will be sent.
\nWe recommend using ngrok (https://ngrok.com) to create a publicly accessible URL that tunnels back to your development server for testing purposes. They have a free tier that will enable you to test the Uplisting API.
\nDelay
\nThe changes received in the payload to this POST call are not applied immediately to the property. Instead, the payload is scheduled for processing by Uplisting and will be applied to the property asynchronously. The payload contains a notification_url that is used to provide a response to the partner indicating success or failure of the relevant updates.
\nThis delay is typically less than 1 minute.
\nNote
\nIf the property ID is not part of the account specified by the API key, the notification URL will not receive a response.
\nIf the payload is considered invalid, the response will be 400 Bad Request with human readable errors indicating why the payload is considered invalid.
The date the rate, availability, MLOS update can either be a single day, specified as date or as a date range using from and to. Note that the night of the to date is always excluded, as it’s considered the morning only. So, to include a range including all nights from 2020-12-01 to the night of 2020-12-10, the to should be set to 2020-12-11.
All attributes can be set for up to 3 years in advance. Any dates before “today” in UTC will be ignored.
\nAvailability is specified either as true if the property can be booked or false if the property is not available to be booked. The availability specified here is for the night of the date specified, or as above to the night before the to date.
The rate for the date, or date range, is specified in the currency of the property that is set on Uplisting. It should be a “commission-free” rate as appropriate markup will be applied to this rate when syncing prices to connected channels.
\navailable, minimum_length_of_stay, day_rate, closed_for_arrival, and closed_for_departure are all optional attributes, meaning you can set a rate and/or availability and/or minimum length of stay and/or closed for arrival and departure restrictions.
Any other attributes added to the payload will be ignored.
\nNotification URL response
\nThe notification URL is specified by the partner and can have any valid format. It must be an HTTPS endpoint.
\nA Base64 encoded partner API key will be included in the HTTP_AUTHORIZATION header to confirm that the response is from Uplisting.
The response will be a list of the correctly applied rate and/or availability and/or MLOS as listed below:
\n{ \"request_id\": \"fe845d4e-9fa2-4f85-b6ee-680d7f97803e\" \"calendar\": { \"days\": [ { \"available\": true, \"day_rate\": 66, \"date\": \"2019-12-20\", \"minimum_length_of_stay\":1, \"closed_for_arrival\": false, \"closed_for_departure\": true }, { \"available\": false, \"from\": \"2019-12-31\", \"to\": \"2020-01-31\" } ] } }