---
openapi: 3.0.2
info:
  title: Jammed Bookings API
  version: 2.0.3
  license:
    name: Jammed Bookings
    url: https://jammed.app
  contact:
    email: api@jammed.app
    url: https://support.jammedapp.com
  x-logo:
    url: "https://jammed.app/static/assets/logo/fill.svg"
    altText: Jammed logo
  description: |
    Jammed API allows you to integrate with the Jammed system, and automate key events within third-party systems. We are adding endpoints and features as we need them and as studios request them. If there's an endpoint you need, please contact us.

    By subscribing to and listening to webhooks your studio can automate sending reminders, automate customer lists and mailing
    systems, anything you can imagine really.

    # Introduction
    Jammed is powering scheduling and bookings for independent creative spaces, and we're building a new way to connect with them.
    You can read more about [Jammed on the support pages](https://support.jammedapp.com).

    Jammed offers webhooks and a polling API, so you can integrate how ever you like with the system.

    You can also see the version history and roadmap for the [Jammed API on the public Github project](https://github.com/jammed-org/api).

    # Authentication
    You authenticate with the API using an API key - this is found in the website settings of the admin section.

    Issue this header with all requests to the API or it will return a `401 Unauthorized` error.

    <SecurityDefinitions />

    # Getting started
    To get started, you'll need to create a Jammed account and create a studio account.

    Once you have setup your studio, head the to Website Setting page and press the 'Enable webhooks' button. From there, you can set the webhook URLs you want Jammed to send to.

x-tagGroups:
  - name: Endpoints
    tags:
      - Booking Endpoints
      - Customer Endpoints
      - Group Endpoints
      - Room Endpoints
  - name: Webhooks
    tags:
      - Booking Webhooks
      - Customer Webhooks
      - Booking Webhooks
  - name: Models
    tags:
      - booking_model
      - customer_model
      - group_model
      - room_model
tags:
  - name: Booking Webhooks
    description: Events that happen with a booking
  - name: Customer Webhooks
    description: Events that happen with a customer
  - name: Group Webhooks
    description: Events that happen with a group/band
  - name: Booking Endpoints
    description: Polling API for bookings
  - name: Customer Endpoints
    description: Polling API for customers
  - name: Group Endpoints
    description: Polling API for groups
  - name: Room Endpoints
    description: Polling API for rooms
  - name: booking_model
    x-displayName: Booking Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/booking" />
  - name: customer_model
    x-displayName: Customer Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/customer" />
  - name: group_model
    x-displayName: Group Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/group" />
  - name: room_model
    x-displayName: Room Model
    description: |
      <SchemaDefinition schemaRef="#/components/schemas/room" />
servers:
  - url: https://api.jammed.app/api/v2/
    description: Jammed API endpoint

paths:
  /bookings.json:
    get:
      tags:
        - Booking Endpoints
      summary: All bookings
      description: Returns all bookings, ordered by creation date
      operationId: getBookings
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/booking'
        "401":
          description: Unauthorized - Invalid API key
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          example: "Bearer <api_key>"

  /bookings/cancelled.json:
    get:
      tags:
        - Booking Endpoints
      summary: Cancelled bookings
      description: Returns all cancelled bookings, ordered by cancellation date
      operationId: getBookingsCancelled
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/booking'
        "401":
          description: Unauthorized - Invalid API key
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          example: "Bearer <api_key>"

  /bookings/started.json:
    get:
      tags:
        - Booking Endpoints
      summary: Started bookings
      description: Returns all started bookings, ordered by start time
      operationId: getBookingsStarted
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/booking'
        "401":
          description: Unauthorized - Invalid API key
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          example: "Bearer <api_key>"

  /bookings/finished.json:
    get:
      tags:
        - Booking Endpoints
      summary: Finished bookings
      description: Returns all finished bookings, ordered by start time
      operationId: getBookingsStarted
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/booking'
        "401":
          description: Unauthorized - Invalid API key
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          example: "Bearer <api_key>"

  /customers.json:
    get:
      tags:
        - Customer Endpoints
      summary: Find all customer
      description: Returns all customers
      operationId: getCustomers
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/customer'
        "401":
          description: Unauthorized - Invalid API key
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          example: "Bearer <api_key>"
    post:
      tags:
        - Customer Endpoints
      summary: Create a customer
      description: |
        Create a new customer on Jammed.

        With a new customer, you must at least provide an **name** and **email address**.

        You can also issue `actions` to the endpoint, to create and invite the customer to set a password - Jammed will then send them an email from your account with a link to set their password.

        You can't create a customer with an email address that already exists as a registered customer on Jammed. You can create a customer with an email address that already exists, so long as the customer is not yet registered on Jammed.

        **Jammed API doesn't accept passwords for customer creation process** - they must be set by the customer themselves in the invitation process to verify the email and to improve security.
      operationId: createCustomer
      responses:
        "201":
          description: Customer created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/customer'
        "401":
          description: Unauthorized - Invalid API key
        "422":
          description: Unprocessable - the customer parameters you provided are invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unprocessable_error'

      requestBody:
        description: Create a new customer in Jammed
        required: true
        content:
          form-data:
            schema:
              $ref: '#/components/schemas/customer_create'
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          example: "Bearer <api_key>"

  /customers/:id.json:
    get:
      tags:
        - Customer Endpoints
      summary: Find a customer by ID
      description: Returns customer with the given ID
      operationId: getCustomer
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/customer'
        "401":
          description: Unauthorized - Invalid API key
        "404":
          description: Not found - Customer with the given ID was not found
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          example: "Bearer <api_key>"
        - name: id
          in: path
          required: true
          schema:
            type: integer

  /groups.json:
    get:
      tags:
        - Group Endpoints
      summary: Find all groups
      description: Returns all groups
      operationId: getGroups
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/group'
        "401":
          description: Unauthorized - Invalid API key
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          example: "Bearer <api_key>"

  /rooms.json:
    get:
      tags:
        - Room Endpoints
      summary: Find all rooms
      description: Returns all rooms
      operationId: getRooms
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/room'
        "401":
          description: Unauthorized - Invalid API key
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
          example: "Bearer <api_key>"

x-webhooks:
  booking.created:
    get:
      summary: booking.created
      description:
        Made when a Jammed booking is made by a customer online, or made
        by an admin user. Use the taken_by parameter to distinguish. When taken online,
        taken_by=online - otherwise it is the name of the admin user that took the
        booking.
      tags:
        - Booking Webhooks
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/booking"
              example:
                "$ref": "#/components/examples/booking"
  booking.updated:
    get:
      summary: booking.updated
      description: Triggered when a booking is updated by a staff member
      tags:
        - Booking Webhooks
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/booking"
              example:
                "$ref": "#/components/examples/booking"
  booking.cancelled:
    get:
      summary: booking.cancelled
      description:
        Triggered when a booking is cancelled by a customer or by a staff
        member. Cancellations will free up this time to other customers wishing to
        book the same time.
      tags:
        - Booking Webhooks
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/booking"
              example:
                "$ref": "#/components/examples/booking"
  booking.reminder:
    get:
      summary: booking.reminder
      description:
        Booking reminders in Jammed are customisable, but by default are
        triggered 24 hours prior to the start of the booking. An email is sent to
        the user, but this event exists so you can also hook in other integrations
        at this point
      tags:
        - Booking Webhooks
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/booking"
              example:
                "$ref": "#/components/examples/booking"
  booking.one_hour_before:
    get:
      summary: booking.one_hour_before
      description: Triggered 1 hour before the booking starts
      tags:
        - Booking Webhooks
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/booking"
              example:
                "$ref": "#/components/examples/booking"
  booking.started:
    get:
      summary: booking.started
      description: Triggered when the booking starts
      tags:
        - Booking Webhooks
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/booking"
              example:
                "$ref": "#/components/examples/booking"
  booking.finished:
    get:
      summary: booking.finished
      description: Triggered when the booking finishes
      tags:
        - Booking Webhooks
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/booking"
              example:
                "$ref": "#/components/examples/booking"
  group.created:
    get:
      summary: group.created
      description:
        Trigger when a group is made on Jammed (also known as bands). It
        can be manually made in the admin interface, or made at booking time if the
        group is new
      tags:
        - Group Webhooks
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/group"
              example:
                "$ref": "#/components/examples/group"
  group.updated:
    get:
      summary: group.updated
      description: Trigger when a group is updated on Jammed (also known as bands)
      tags:
        - Group Webhooks
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/group"
              example:
                "$ref": "#/components/examples/group"
  group.deleted:
    get:
      summary: group.deleted
      description: Trigger when a group is deleted on Jammed (also known as bands)
      tags:
        - Group Webhooks
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/group"
              example:
                "$ref": "#/components/examples/group"
  customer.created:
    get:
      summary: customer.created
      description:
        Trigger when a customer is made on Jammed. It can be manually made
        in the admin interface, or made at booking time if the customer is new
      tags:
        - Customer Webhooks
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/customer"
              example:
                "$ref": "#/components/examples/customer"
  customer.updated:
    get:
      summary: customer.updated
      description: Trigger when a customer is updated on Jammed
      tags:
        - Customer Webhooks
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/customer"
              example:
                "$ref": "#/components/examples/customer"
  customer.deleted:
    get:
      summary: customer.deleted
      description: Trigger when a customer is deleted on Jammed
      tags:
        - Customer Webhooks
      responses:
        "200":
          description: Response
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/customer"
              example:
                "$ref": "#/components/examples/customer"
components:
  schemas:
    customer_create_body:
      type: object
      title: Customer info
      properties:
        name:
          type: string
          title: Name
          description: ""
          properties: {}
        email:
          type: string
          title: Email
          description: ""
          properties: {}
        mobile:
          type: string
          title: Mobile
          description: ""
          properties: {}
        reminders_opt_in:
          type: boolean
          title: Reminders opt-in
          description: "Whether this customer wants to receive reminders"
        mailing_list_opt_in:
          type: boolean
          title: Mailing list opt-in
          description: "Whether this customer wants to be on the mailing list"
      required:
        - name
        - email
    customer_create_actions:
      type: object
      title: Customer creation actions - optional
      properties:
        invite:
          type: boolean
          title: Invite
          description: Invite this customer to set a password on Jammed. An email will be sent to them and the invite code will last 2 days

    customer_create:
      type: object
      description: ""
      properties:
        customer:
          "$ref": "#/components/schemas/customer_create_body"
        actions:
          "$ref": "#/components/schemas/customer_create_actions"

    short_room:
      type: object
      title: Basic room info
      properties:
        name:
          type: string
          title: Name
          description: ""
        code:
          type: string
          title: Code
          description: ""
      required:
        - name
      additionalProperties: false
    short_customer:
      type: object
      title: Basic customer info
      description: ""
      properties:
        name:
          type: string
          title: Name
          description: ""
          properties: {}
        email:
          type: string
          title: Email
          description: ""
          properties: {}
        mobile:
          type: string
          title: Mobile
          description: ""
          properties: {}
        avatar:
          type: string
          title: Avatar
          description: ""
          properties: {}
        reminders_opt_in:
          type: boolean
          title: Reminders opt-in
          description: "Whether this customer wants to receive reminders"
        mailing_list_opt_in:
          type: boolean
          title: Mailing list opt-in
          description: "Whether this customer wants to be on the mailing list"
      required:
        - name
      additionalProperties: false
    short_group:
      type: object
      title: Basic group info
      description: ""
      properties:
        name:
          type: string
          title: Name
          description: ""
          properties: {}
        code:
          type: string
          title: Code
          description: ""
          properties: {}
        number_of_members:
          type: integer
          title: NumberOfMembers
          description: ""
          properties: {}
      required: []
      additionalProperties: false
    booking:
      type: object
      properties:
        group:
          type: object
          "$ref": "#/components/schemas/short_group"
        customer:
          "$ref": "#/components/schemas/short_customer"
        room:
          "$ref": "#/components/schemas/short_room"
        code:
          type: string
          title: Code
          description: ""
        id:
          type: string
          title: id
          description: "Same as code"
        created_at:
          type: integer
          title: CreatedAt
          description: "Unix timestamp from epoch"
        updated_at:
          type: integer
          title: UpdatedAt
          description: "Unix timestamp from epoch"
        price:
          type: integer
          title: Price
          description: ""
        price_currency:
          type: string
          title: PriceCurrency
          description: ""
        recording:
          type: boolean
          title: Recording
          description: ""
        regular:
          type: boolean
          title: Regular
          description: ""
        title:
          type: string
          title: Title
          description: ""
        start_at:
          type: integer
          title: StartAt
          description: "Unix timestamp from epoch"
        end_at:
          type: integer
          title: EndAt
          description: "Unix timestamp from epoch"
        duration:
          type: integer
          title: Duration
          description: "The duration of the booking in seconds"
        duration_hours:
          type: float
          title: DurationHours
          description: "The duration of the booking in hours, e.g. 1pm-2.30pm = `2.5` hours"
        duration_full_hours:
          type: integer
          title: DurationFullHours
          description: "The duration of the booking in hours, rounded up to each full hour, e.g. 1pm-2.30pm = `3` hours"
        number_expected:
          type: integer
          title: NumberExpected
          description: ""
        has_amount_due:
          type: boolean
          title: HasAmountDue
          description: ""
        remaining_amount:
          type: integer
          title: RemainingAmount
          description: ""
        taken_by:
          type: string
          title: TakenBy
          description: ""
    room:
      type: object
      properties:
        id:
          type: string
          title: id
        code:
          type: string
          title: Code
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        space_for:
          type: integer
          title: SpaceFor
          description: "The capacity of the room"
        order:
          type: integer
          title: Order
        twenty_four_hour_booking:
          type: boolean
          title: TwentyFourHourBooking
          description: "Whether the room can be booked 24 hours a day"
        space_type:
          type: string
          title: SpaceType
          description: "The type of space the room is"
        hex_colour:
          type: string
          title: HexColour
          description: "The hex colour of the room on the dashboard"
        active:
          type: boolean
          title: Active
          description: "Whether the room is active for Jammed online bookings"
        images:
          type: array
          title: Images
          description: "The images of the room"
          items:
            type: object
            properties:
              original:
                type: string
                title: original
                description: "Image URL"
        data:
          type: object
          title: Data
          description: "The hidden data of the room - can be set and used by back-end systems"
        prices_set:
          type: integer
          title: PricesSet
          description: "The count of prices set for the room"
        price_to:
          type: string
          title: PriceTo
          description: "The maximum price for the room"
        price_from:
          type: string
          title: PriceFrom
          description: "The minimum price for the room"

    customer:
      type: object
      properties:
        name:
          type: string
          title: Name
          description: ""
        email:
          type: string
          title: Email
          description: ""
        mobile:
          type: string
          title: Mobile
          description: ""
        avatar:
          type: string
          title: Avatar
          description: ""
        status:
          type: string
          title: Status
          description: ""
        reminders_opt_in:
          type: boolean
          title: Reminders opt-in
          description: "Whether this customer wants to receive reminders"
        mailing_list_opt_in:
          type: boolean
          title: Mailing list opt-in
          description: "Whether this customer wants to be on the mailing list"
        bands:
          type: array
          title: Bands or Groups
          description: ""
          items:
            type: object
            title: ""
            description: ""
            "$ref": "#/components/schemas/short_group"
        signed_up:
          type: boolean
          title: SignedUp
          description: ""
        signed_up_at:
          type: integer
          title: SignedUpAt
          description: ""
        regular_bookings_count:
          type: integer
          title: RegularBookingsCount
          description: ""
        regular_bookings:
          type: array
          title: RegularBookings
          description: ""
          items:
            type: object
            title: ""
            description: ""
            properties:
              name:
                type: string
                title: Name
                description: ""
              id:
                type: integer
                title: Id
                description: ""
        bookings_count:
          type: integer
          title: BookingsCount
          description: ""
        created_at:
          type: integer
          title: CreatedAt
          description: ""
        updated_at:
          type: integer
          title: UpdatedAt
          description: ""
        last_booking_at:
          type: integer
          title: LastBookingAt
          description: ""
    group:
      type: object
      properties:
        name:
          type: string
          title: Name
          description: ""
        group_type:
          type: string
          title: GroupType
          description: ""
        number_of_members:
          type: integer
          title: NumberOfMembers
          description: ""
        customers:
          type: array
          title: Customers
          description: ""
          items:
            type: object
            title: ""
            description: ""
            "$ref": "#/components/schemas/short_customer"
        regular_bookings:
          type: array
          title: RegularBookings
          description: ""
          items:
            type: object
            title: ""
            description: ""
            properties:
              name:
                type: string
                title: Name
                description: ""
              id:
                type: integer
                title: Id
                description: ""
        customer_count:
          type: integer
          title: CustomerCount
          description: ""
        regular_bookings_count:
          type: integer
          title: RegularBookingsCount
          description: ""
        bookings_count:
          type: integer
          title: BookingsCount
          description: ""
        created_at:
          type: integer
          title: CreatedAt
          description: ""
        updated_at:
          type: integer
          title: UpdatedAt
          description: ""
        last_booking_at:
          type: integer
          title: LastBookingAt
          description: ""
    unprocessable_error:
      type: object
      properties:
        status:
          type: string
          description: Error status
          example: "error"
        message:
          type: string
          description: Error message
          example: "The customer parameters you provided are invalid"
  examples:
    booking:
      name: Rush
      group_type: band
      number_of_members: 3
      customers:
        - name: Geddy Lee
          email: geddy22@yahoo.ca
        - name: Neil Peart
          email: theprofessor2112@gmail.com
          mobile: "+447584948502"
        - name: Alex Lifeson
          email: alex-lifeson@me.com
          mobile: "+442072983029"
      customer_count: 3
      regular_bookings:
        - name: Monday 8pm Red Room
          id: 503
      regular_bookings_count: 1
      bookings_count: 61
      created_at: 1646247874
      updated_at: 1646247874
    customer:
      email: Geddy Lee
      avatar: https://www.gravatar.com/avatar/02e414a53149473ddd8ed541fac40b6f?d=mp&s=45
      status: unregistered
      signed_up: false
      bands:
        - name: Rush
          code: DI3EK30SP
          number: 3
          booking_count: 9
      regular_bookings_count: 1
      regular_bookings:
        - name: Geddy Lee (Rush)
          id: 2112
      bookings_count: 9
      last_booking_at: 1643799530
      created_at: 1643799530
      updated_at: 1643799530
    group:
      name: Rush
      group_type: band
      number_of_members: 3
      customers:
        - name: Geddy Lee
          email: geddy22@yahoo.ca
          mobile: "+447584948502"
        - name: Neil Peart
          email: theprofessor2112@gmail.com
          mobile: "+447584948502"
        - name: Alex Lifeson
          email: alex-lifeson@me.com
          mobile: "+442072983029"
      customer_count: 3
      regular_bookings:
        - name: Geddy Lee (Rush)
          id: 2112
      regular_bookings_count: 1
      bookings_count: 6171
      created_at: 1646247874
      updated_at: 1646247874
  securitySchemes:
    apiKey:
      type: apiKey
      name: "Authorization: 'Bearer <api-key>'"
      in: header
      description: |
        Issue a http header with the key 'Authorization' and value 'Bearer api_key'