Uplisting Bookings API

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