Read guest records associated with bookings - name, contact details, and identity-verification status. Guest resources are modeled from Uplisting's documented booking and guest-verification features; confirm exact paths under the invite-only reference.
openapi: 3.0.3
info:
title: Uplisting Public and Partner API
description: >-
Uplisting is short-term / vacation rental management software and a channel
manager. This OpenAPI describes Uplisting's invite-only Public and Partner
REST API, which lets partners read properties, bookings, availability, and
calendar data (prices and restrictions), create confirmed bookings, and
register webhooks that push booking changes.
Base URL: https://connect.uplisting.io (production). Staging uses the same
paths on a different base domain; accounts and API keys are
environment-specific.
Authentication is HTTP Basic: send `Authorization: Basic <base64(api_key)>`.
API keys are generated on the Connect page in the Uplisting app. V2 endpoints
additionally require a Client ID (partner identifier). API access is
invite-only - request access from support@uplisting.io.
Grounding note: the Users, Properties, Bookings, Availability, and Calendar
surfaces and the webhook behavior are confirmed from Uplisting's public
documentation. The exact request/response schemas and the Rates, Guests, and
Messages resources are MODELED from Uplisting's documented product behavior
because the full reference is behind an invite-only Postman collection.
Operations that are modeled are marked with `x-modeled: true`.
version: '1.0'
contact:
name: Uplisting Support
url: https://support.uplisting.io/docs/api
email: support@uplisting.io
servers:
- url: https://connect.uplisting.io
description: Production
security:
- basicAuth: []
tags:
- name: Account
description: Authenticated account/user context.
- name: Bookings
description: Reservations across all connected channels.
- name: Properties
description: Properties (listings) in the account.
- name: Availability
description: Properties available for a date range.
- name: Calendar
description: Availability, prices, and restrictions per property and date.
- name: Rates
description: Nightly rates and price adjustments (modeled via the calendar).
- name: Guests
description: Guest records tied to bookings (modeled).
- name: Messages
description: Guest messaging via the unified inbox (modeled).
- name: Webhooks
description: Endpoints that receive booking change events.
paths:
/users/me:
get:
operationId: getCurrentUser
tags:
- Account
summary: Get the authenticated user
description: >-
Returns the account/user associated with the supplied API key. Commonly
used to validate credentials and discover account context. Confirmed
endpoint.
responses:
'200':
description: The authenticated user/account.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/properties:
get:
operationId: listProperties
tags:
- Properties
summary: List properties
description: >-
Lists the properties (listings) in the account, including the property
slug used to build direct booking and payment-page links. Confirmed
endpoint; response fields modeled.
responses:
'200':
description: A list of properties.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Property'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/properties/{propertyId}:
get:
operationId: getProperty
tags:
- Properties
summary: Get a property
description: Retrieves a single property by its identifier. Confirmed surface; response fields modeled.
parameters:
- $ref: '#/components/parameters/PropertyId'
responses:
'200':
description: The property.
content:
application/json:
schema:
$ref: '#/components/schemas/Property'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/bookings:
get:
operationId: listBookings
tags:
- Bookings
summary: List bookings
description: >-
Returns a snapshot list of bookings across connected channels. Uplisting
recommends using this to seed state, then relying on webhooks for
subsequent changes. Confirmed surface; query and response fields modeled.
parameters:
- name: property_id
in: query
required: false
schema:
type: string
description: Filter bookings to a single property.
- name: check_in_from
in: query
required: false
schema:
type: string
format: date
description: Return bookings with a check-in on or after this date.
- name: check_in_to
in: query
required: false
schema:
type: string
format: date
description: Return bookings with a check-in on or before this date.
responses:
'200':
description: A list of bookings.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Booking'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
post:
operationId: createBooking
tags:
- Bookings
summary: Create a confirmed booking
description: >-
Creates a confirmed booking on a property for a date range. Confirmed
surface (returns 201 Created); request/response fields modeled.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BookingCreate'
responses:
'201':
description: The created booking.
content:
application/json:
schema:
$ref: '#/components/schemas/Booking'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
/bookings/{bookingId}:
get:
operationId: getBooking
tags:
- Bookings
summary: Get a booking
description: Retrieves a single booking by identifier. Confirmed surface; response fields modeled.
parameters:
- $ref: '#/components/parameters/BookingId'
responses:
'200':
description: The booking.
content:
application/json:
schema:
$ref: '#/components/schemas/Booking'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
patch:
operationId: updateBooking
tags:
- Bookings
summary: Update a booking
description: Updates mutable fields on a booking (for example status). Modeled.
x-modeled: true
parameters:
- $ref: '#/components/parameters/BookingId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BookingUpdate'
responses:
'200':
description: The updated booking.
content:
application/json:
schema:
$ref: '#/components/schemas/Booking'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/availability:
get:
operationId: listAvailability
tags:
- Availability
summary: List available properties for a date range
description: >-
Returns the properties that are available for a given check-in /
check-out date range, optionally filtered by number of guests. Confirmed
surface; query and response fields modeled.
parameters:
- name: check_in
in: query
required: true
schema:
type: string
format: date
description: Check-in date (YYYY-MM-DD).
- name: check_out
in: query
required: true
schema:
type: string
format: date
description: Check-out date (YYYY-MM-DD).
- name: guests
in: query
required: false
schema:
type: integer
minimum: 1
description: Minimum guest capacity to filter by.
responses:
'200':
description: Properties available for the requested range.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AvailableProperty'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/properties/{propertyId}/calendar:
get:
operationId: getCalendar
tags:
- Calendar
summary: Get calendar for a property
description: >-
Returns availability, prices, and restrictions (for example minimum
stay, closed to arrival/departure) for a property across a date range.
Confirmed surface; response fields modeled.
parameters:
- $ref: '#/components/parameters/PropertyId'
- name: from
in: query
required: true
schema:
type: string
format: date
description: Start date of the calendar window (YYYY-MM-DD).
- name: to
in: query
required: true
schema:
type: string
format: date
description: End date of the calendar window (YYYY-MM-DD).
responses:
'200':
description: Calendar days for the property.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/CalendarDay'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
put:
operationId: updateCalendar
tags:
- Calendar
summary: Update calendar for a property
description: >-
Submits availability, price, and/or restriction updates for a property
over a date range. Calendar updates are accepted asynchronously and
return HTTP 202. Confirmed 202 behavior; request fields modeled.
parameters:
- $ref: '#/components/parameters/PropertyId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CalendarUpdate'
responses:
'202':
description: The calendar update was accepted for processing.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/TooManyRequests'
/properties/{propertyId}/rates:
put:
operationId: updateRates
tags:
- Rates
summary: Update nightly rates for a property
description: >-
Sets nightly rates / price adjustments per date for a property; updates
propagate to connected channels. Modeled from the documented calendar and
pricing behavior - rates are surfaced through the calendar in the public
product.
x-modeled: true
parameters:
- $ref: '#/components/parameters/PropertyId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RatesUpdate'
responses:
'202':
description: The rate update was accepted for processing.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/guests:
get:
operationId: listGuests
tags:
- Guests
summary: List guests
description: Lists guest records tied to bookings. Modeled.
x-modeled: true
responses:
'200':
description: A list of guests.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Guest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/guests/{guestId}:
get:
operationId: getGuest
tags:
- Guests
summary: Get a guest
description: Retrieves a single guest record, including identity-verification status. Modeled.
x-modeled: true
parameters:
- $ref: '#/components/parameters/GuestId'
responses:
'200':
description: The guest.
content:
application/json:
schema:
$ref: '#/components/schemas/Guest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
/bookings/{bookingId}/messages:
get:
operationId: listMessages
tags:
- Messages
summary: List messages for a booking
description: Lists guest messages tied to a booking from the unified inbox. Modeled.
x-modeled: true
parameters:
- $ref: '#/components/parameters/BookingId'
responses:
'200':
description: A list of messages.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Message'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
post:
operationId: sendMessage
tags:
- Messages
summary: Send a message on a booking
description: Sends a guest message on a booking through the unified inbox. Modeled.
x-modeled: true
parameters:
- $ref: '#/components/parameters/BookingId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageCreate'
responses:
'201':
description: The sent message.
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/webhooks:
get:
operationId: listWebhooks
tags:
- Webhooks
summary: List webhook endpoints
description: Lists the registered webhook endpoints for the account. Confirmed webhook mechanism; shape modeled.
responses:
'200':
description: A list of webhook endpoints.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Webhook'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
post:
operationId: createWebhook
tags:
- Webhooks
summary: Register a webhook endpoint
description: >-
Registers an endpoint to receive booking created, updated, and removed
events. The endpoint must return a 2xx within 5 seconds; after 5
consecutive delivery failures it is auto-disabled. Confirmed behavior;
request/response fields modeled.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookCreate'
responses:
'201':
description: The registered webhook endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
/webhooks/{webhookId}:
delete:
operationId: deleteWebhook
tags:
- Webhooks
summary: Delete a webhook endpoint
description: Removes a registered webhook endpoint. Confirmed webhook mechanism; shape modeled.
parameters:
- $ref: '#/components/parameters/WebhookId'
responses:
'204':
description: The webhook endpoint was deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic auth. Send `Authorization: Basic <base64(api_key)>`, where
api_key is generated on the Uplisting Connect page. V2 endpoints also
require a Client ID partner identifier.
parameters:
PropertyId:
name: propertyId
in: path
required: true
schema:
type: string
description: The property (listing) identifier.
BookingId:
name: bookingId
in: path
required: true
schema:
type: string
description: The booking identifier.
GuestId:
name: guestId
in: path
required: true
schema:
type: string
description: The guest identifier.
WebhookId:
name: webhookId
in: path
required: true
schema:
type: string
description: The webhook endpoint identifier.
responses:
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
UnprocessableEntity:
description: The request was well-formed but failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequests:
description: Rate limit exceeded. Back off and retry.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
User:
type: object
description: The authenticated account/user. Fields modeled.
properties:
id:
type: string
name:
type: string
email:
type: string
format: email
account_id:
type: string
Property:
type: object
description: A property (listing). Fields modeled.
properties:
id:
type: string
name:
type: string
slug:
type: string
description: Slug used to build direct booking and payment-page URLs.
address:
type: string
bedrooms:
type: integer
max_guests:
type: integer
currency:
type: string
example: USD
active:
type: boolean
AvailableProperty:
type: object
description: A property returned by an availability search. Fields modeled.
properties:
id:
type: string
name:
type: string
slug:
type: string
price_total:
type: number
currency:
type: string
Booking:
type: object
description: A reservation. Fields modeled.
properties:
id:
type: string
property_id:
type: string
channel:
type: string
description: Source channel (airbnb, vrbo, booking_com, direct).
enum:
- airbnb
- vrbo
- booking_com
- direct
status:
type: string
enum:
- confirmed
- cancelled
- pending
check_in:
type: string
format: date
check_out:
type: string
format: date
guests:
type: integer
guest:
$ref: '#/components/schemas/Guest'
total_price:
type: number
currency:
type: string
created_at:
type: string
format: date-time
BookingCreate:
type: object
description: Payload to create a confirmed booking. Fields modeled.
required:
- property_id
- check_in
- check_out
properties:
property_id:
type: string
check_in:
type: string
format: date
check_out:
type: string
format: date
guests:
type: integer
guest:
$ref: '#/components/schemas/GuestCreate'
BookingUpdate:
type: object
description: Mutable booking fields. Modeled.
properties:
status:
type: string
enum:
- confirmed
- cancelled
CalendarDay:
type: object
description: One day of calendar data for a property. Fields modeled.
properties:
date:
type: string
format: date
available:
type: boolean
price:
type: number
currency:
type: string
min_stay:
type: integer
closed_to_arrival:
type: boolean
closed_to_departure:
type: boolean
CalendarUpdate:
type: object
description: Calendar update over a date range. Fields modeled.
required:
- from
- to
properties:
from:
type: string
format: date
to:
type: string
format: date
available:
type: boolean
price:
type: number
min_stay:
type: integer
closed_to_arrival:
type: boolean
closed_to_departure:
type: boolean
RatesUpdate:
type: object
description: Nightly rate update over a date range. Modeled.
required:
- from
- to
- price
properties:
from:
type: string
format: date
to:
type: string
format: date
price:
type: number
currency:
type: string
Guest:
type: object
description: A guest tied to a booking. Modeled.
properties:
id:
type: string
first_name:
type: string
last_name:
type: string
email:
type: string
format: email
phone:
type: string
identity_verified:
type: boolean
GuestCreate:
type: object
description: Guest details supplied when creating a booking. Modeled.
properties:
first_name:
type: string
last_name:
type: string
email:
type: string
format: email
phone:
type: string
Message:
type: object
description: A guest message from the unified inbox. Modeled.
properties:
id:
type: string
booking_id:
type: string
direction:
type: string
enum:
- inbound
- outbound
channel:
type: string
body:
type: string
created_at:
type: string
format: date-time
MessageCreate:
type: object
description: Payload to send a guest message. Modeled.
required:
- body
properties:
body:
type: string
Webhook:
type: object
description: A registered webhook endpoint. Fields modeled.
properties:
id:
type: string
url:
type: string
format: uri
events:
type: array
items:
type: string
enum:
- booking.created
- booking.updated
- booking.removed
enabled:
type: boolean
WebhookCreate:
type: object
description: Payload to register a webhook endpoint. Fields modeled.
required:
- url
properties:
url:
type: string
format: uri
events:
type: array
items:
type: string
enum:
- booking.created
- booking.updated
- booking.removed
Error:
type: object
properties:
error:
type: string
message:
type: string