Launch27 Booking Helpers API

openapi: 3.2.0
info:
  title: Launch27 Booking Helpers API
  description: Unofficial-but-real, actively used REST API for Launch27, a booking and scheduling platform for cleaning service businesses.
  version: '2.1'
  contact:
    name: API Evangelist
    email: kin@apievangelist.com
servers:
- url: https://{tenant}.launch27.com/v1
  description: Production (per-tenant subdomain)
  variables:
    tenant:
      default: acme
      description: Launch27 client account subdomain.
- url: https://{tenant}.l27.co/v1
  description: Testing/sandbox (per-tenant subdomain)
  variables:
    tenant:
      default: acme-sandbox
      description: Launch27 sandbox account subdomain.
security:
- bearerAuth: []
tags:
- name: Booking Helpers
  description: Supporting data for building and pricing a booking form.
paths:
  /booking/form:
    get:
      operationId: getBookingForm
      tags:
      - Booking Helpers
      summary: Get booking form setup
      security: []
      parameters:
      - name: type
        in: query
        required: false
        description: Booking form type (requires features.new_booking_form_widget).
        schema:
          type: string
          enum:
          - cleaning
          - auto
          - lawn
          - carpet
      responses:
        '200':
          description: Booking form headings, system fields, paragraphs, and appearance settings.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /booking/services:
    get:
      operationId: getBookingServices
      tags:
      - Booking Helpers
      summary: Get services available for booking
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/BookingUuid'
      - $ref: '#/components/parameters/LocationId'
      responses:
        '200':
          description: List of available services.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
  /booking/spots:
    post:
      operationId: getBookingSpots
      tags:
      - Booking Helpers
      summary: Get available spots for booking
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpotsRequest'
      responses:
        '200':
          description: Available spots by date (or grid + days if grid=true).
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
  /booking/location:
    post:
      operationId: getBookingLocation
      tags:
      - Booking Helpers
      summary: Resolve location for a booking address
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LocationRequest'
      responses:
        '200':
          description: Resolved location.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Location'
  /booking/frequencies:
    get:
      operationId: getBookingFrequencies
      tags:
      - Booking Helpers
      summary: Get frequencies available for booking
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/BookingUuid'
      - $ref: '#/components/parameters/LocationId'
      responses:
        '200':
          description: List of configured frequencies.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Frequency'
  /booking/frequencies/{id}/next:
    post:
      operationId: getNextBookingDateForFrequency
      tags:
      - Booking Helpers
      summary: Get next recurring booking date for a frequency
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        description: Frequency unique ID.
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - date
              properties:
                date:
                  type: string
                  description: YYYY-MM-DDTHH:MM:SS
      responses:
        '200':
          description: Next recurring date.
          content:
            application/json:
              schema:
                type: object
                properties:
                  date:
                    type: string
                    format: date-time
        '422':
          description: Schema error, or frequency is not recurring.
  /booking/custom_fields:
    get:
      operationId: getBookingCustomFields
      tags:
      - Booking Helpers
      summary: Get custom fields for booking
      security:
      - bearerAuth: []
      - {}
      parameters:
      - $ref: '#/components/parameters/BookingUuid'
      responses:
        '200':
          description: List of custom fields.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomField'
  /booking/estimate_price:
    post:
      operationId: estimateBookingPrice
      tags:
      - Booking Helpers
      summary: Estimate price for a booking
      security:
      - bearerAuth: []
      - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PriceEstimateRequest'
      responses:
        '200':
          description: Price estimate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PriceEstimate'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Customer has no access to booking.
components:
  responses:
    Unauthorized:
      description: Missing/invalid Authorization header, or invalid credentials.
  schemas:
    Location:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    PriceEstimateRequest:
      type: object
      required:
      - service_date
      - frequency_id
      - services
      properties:
        email:
          type: string
          format: email
        booking_uuid:
          type:
          - string
          - 'null'
        original_booking_id:
          type:
          - integer
          - 'null'
        service_date:
          type: string
        location_id:
          type:
          - integer
          - 'null'
        frequency_id:
          type: integer
        services:
          type: array
          items:
            $ref: '#/components/schemas/ServiceSelection'
        discount_code:
          type:
          - string
          - 'null'
        tip:
          type:
          - number
          - 'null'
        tip_recurring:
          type:
          - boolean
          - 'null'
        price_adjustment:
          type:
          - number
          - 'null'
          description: Staff-only.
        final_price:
          type:
          - number
          - 'null'
          description: Staff-only.
    PriceEstimate:
      type: object
      properties:
        services:
          type: number
        extras:
          type: number
        discount_amount:
          type: number
        discount_message:
          type: string
        giftcard_amount:
          type: number
        price_adjustment:
          type: number
        tax:
          type: object
          additionalProperties: true
        tip:
          type: number
        total:
          type: number
        next_total:
          type: number
        duration:
          type: integer
        price_for_frequency:
          type: number
        price_for_discount_by_code:
          type: number
        price_recurring_for_frequency:
          type: number
    Frequency:
      type: object
      properties:
        id:
          type: integer
        interval:
          type: string
          description: '''o'' = one time; otherwise a recurring interval pattern like 1w, 2m15d.'
        name:
          type: string
        percent:
          type: number
        amount:
          type: number
        exclude_first:
          type: boolean
        default:
          type: boolean
    SpotsRequest:
      type: object
      required:
      - date
      - days
      - mode
      properties:
        date:
          type: string
          format: date
        days:
          type: integer
          minimum: 1
          maximum: 7
        mode:
          type: string
          enum:
          - new
          - reschedule
        location_id:
          type:
          - integer
          - 'null'
        grid:
          type:
          - boolean
          - 'null'
    LocationRequest:
      type: object
      properties:
        address:
          type:
          - string
          - 'null'
        city:
          type:
          - string
          - 'null'
        state:
          type:
          - string
          - 'null'
        zip:
          type:
          - string
          - 'null'
    ServiceSelection:
      type: object
      required:
      - id
      properties:
        id:
          type: integer
        hourly:
          type:
          - object
          - 'null'
          properties:
            quantity:
              type: integer
            minutes:
              type: integer
        extras:
          type:
          - array
          - 'null'
          items:
            type: object
            required:
            - id
            - quantity
            properties:
              id:
                type: integer
              quantity:
                type: integer
              recurring:
                type:
                - boolean
                - 'null'
        pricing_parameters:
          type:
          - array
          - 'null'
          items:
            type: object
            required:
            - id
            - quantity
            properties:
              id:
                type: integer
              quantity:
                type: integer
    PricingParameter:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        price:
          type: number
        quantity_minimum:
          type: integer
        quantity_maximum:
          type: integer
    Extra:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        price:
          type: number
        quantity_based:
          type: boolean
        recurring:
          type: boolean
        discount_by_frequency:
          type: boolean
        discount_by_code:
          type: boolean
    CustomField:
      type: object
      properties:
        id:
          type: integer
        code:
          type: string
        label:
          type: string
        control_type:
          type: string
          enum:
          - single_line
          - multi_line
          - radio_buttons
          - checkboxes
          - drop_down
          - plain_text
          - date
          - datetime
          - checkbox
        value_required:
          type: boolean
        visible:
          type: boolean
        ordering:
          type: integer
        default_value:
          type: string
        options:
          type: array
          items:
            type: object
            additionalProperties: true
    Service:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        price:
          type: number
        commercial:
          type: boolean
        discount_by_frequency:
          type: boolean
        discount_by_code:
          type: boolean
        hourly:
          type:
          - object
          - 'null'
          additionalProperties: true
        extras:
          type: array
          items:
            $ref: '#/components/schemas/Extra'
        pricing_parameters:
          type: array
          items:
            $ref: '#/components/schemas/PricingParameter'
  parameters:
    BookingUuid:
      name: booking_uuid
      in: query
      required: false
      description: Booking digest; required (and requires auth) when requesting for an existing booking.
      schema:
        type: string
    LocationId:
      name: location_id
      in: query
      required: false
      description: Unique ID of location; default location used if omitted.
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT returned as `bearer` in the Login response. Sent as `Authorization: Bearer <JWT>`. A legacy `email:token` form (Authorization: email:token) existed but was retired March 1, 2023.'