Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

SuperSaaS Python SDK

Online bookings/appointments/calendars in Python using the SuperSaaS scheduling platform -

The SuperSaaS API provides services that can be used to add online booking and scheduling functionality to an existing website or CRM software.


  1. Register for a (free) SuperSaaS account, and
  2. get your account name and API key on the Account Info page.

Python 2.7 or 3.*

No external libraries. The supporting urllib/urllib2 and json/simplejson standard libs are loaded conditionally.


The SDK is available from PyPi and can be installed using pip, e.g.

$ pip install supersaas-api-client


The SuperSaaS client can be created in two ways:

  1. Simply initialize a Client() instance
  2. Obtain the singleton instnace by calling the helper method

Creating a normal instance

Simply create a new client instance manually:

from SuperSaaS import Client, Configuration

# Initialize client with authorization credentials
config = Configuration()

client = Client(config)
client.account_name = 'your_account_name'
client.api_key = 'your_api_key'

# Do API calls

Get(or create) the singleton instance

Use the helper method Client.instance() to deal with the singleton instance:

from SuperSaaS import Client

# Initialize the singleton with authorization credentials
    account_name = 'your_account_name',
    api_key = 'your_api_key'

# Do API calls

Configuring the client

Note, ensure that configure is called before instance, otherwise the client will be initialized with configuration defaults.

If the client isn't configured explicitly, it will use default ENV variables for the account name and api key.

ENV['SSS_API_ACCOUNT_NAME'] = 'your-env-supersaas-account-name'
ENV['SSS_API_KEY'] = 'your-env-supersaas-api-key' 
Client.instance().account_name #=> 'your-env-supersaas-account-name'
Client.instance().api_key #=> 'your-env-supersaas-api-key'

All configuration options can be individually set on the client.

Client.instance().api_key = 'xxxxxxxxxxxxxxxxxxxxxx' 
Client.instance().verbose = True

Avaiable configuration options are:

Attribute Default value Descriptions
account_name '' Your account name
api_key '' Your api key
verbose False Whether to print the HTTP request/response data to console. For debugging purpose.
host Configuration.DEFAULT_HOST Server host. Normally you won't need to specify this.

For implementaion detail check the Configuration() class in SuperSaas/

API Methods

Details of the data structures, parameters, and values can be found on the developer documentation site:

List Schedules

Get all account schedules:


List Resource

Get all services/resources by schedule_id:


Note: does not work for capacity type schedules.

Create User

Create a user with user attributes params:

Client.instance().users.create(attributes={'full_name': 'Example Name', 'email': ''}, user_id=None, webhook=True)

Update User

Update a user by user_id with user attributes params:

Client.instance().users.update(user_id=12345, attributes={'full_name': 'New Name'})

Delete User

Delete a single user by user_id:


Get User

Get a single user by user_id:


List Users

Get all users with optional form and limit/offset pagination params:

Client.instance().users.list(form=False, limit=25, offset=0)

Create Appointment/Booking

Create an appointment by schedule_id and user_id with appointment attributes and form and webhook params:

Client.instance().appointments.create(schedule_id=12345, user_id=67890, attributes={'full_name': 'Example Name', 'email': '', 'slot_id': 12345}, form=True, webhook=True)

Update Appointment/Booking

Update an appointment by schedule_id and appointment_id with appointment attributes params:

Client.instance().appointments.update(schedule_id=12345, appointment_id=67890, attributes={'full_name': 'New Name'}, webhook=True)

Delete Appointment/Booking

Delete a single appointment by schedule_id and appointment_id:

Client.instance().appointments.delete(schedule_id=12345, appointment_id=67890, webhook=True)

Get Appointment/Booking

Get a single appointment by schedule_id and appointment_id:

Client.instance().appointments.get(schedule_id=12345, appointment_id=67890)

List Appointments/Bookings

List appointments by schedule_id, with form and start_time and limit view param:

Client.instance().appointments.list(schedule_id=12345, form=True,, limit=50)

Get Agenda

Get agenda (upcoming) appointments by schedule_id and user_id, with from_time view param:

Client.instance().appointments.agenda(schedule_id=12345, user_id=67890,

Get Agenda Slots

Get agenda (upcoming) slots by schedule_id and user_id, with from_time view param:

Client.instance().appointments.agenda_slots(schedule_id=12345, user_id=67890,

Note: only works for capacity type schedules.

Get Available Appointments/Bookings

Get available appointments by schedule_id, with from_time time and length_minutes and resource params:

Client.instance().appointments.available(schedule_id=12345, from_time='2018-01-31 00:00:00', length_minutes=15, resource='My Class')

Get Recent Changes

Get recently changed appointments by schedule_id, with from_time view param:

Client.instance().appointments.changes(schedule_id=12345, from_time='2018-01-31 00:00:00', True)

Get Recent Changes Slots

Get recently changed slot appointment by schedule_id, with from_time view params:

Client.instance().appointments.changes_slots(schedule_id=12345, from_time='2018-01-31 00:00:00')

Note: only works for capacity type schedules.

Get list of appointments

Get list of appointments by schedule_id, with today, from time, to time and slot view param:

Client.instance().appointments.range(schedule_id=12345, today=True, from_time='2020-01-31 00:00:00',from_time='2020-02-01 00:00:00' slot=False)

List Template Forms

Get all forms by template superform_id, with from_time param:

Client.instance().forms.list(superform_id=12345, from_time='2018-01-31 00:00:00')

Get Form

Get a single form by form_id:


Error Handling

The API Client raises a custom Error for HTTP errors and invalid input. Rescue from SuperSaaS.Error when making API requests. e.g.

from SuperSaaS import Client, Error
except Error:
    # Handle error

Validation errors are assigned to the response model. e.g.

appointment = Client.instance().appointments.create(12345, {bad_field_name: ''})
appointment.errors #=> [{"status":"400","title":"Bad request: unknown attribute 'bad_field_name' for Booking."}]

Additional Information



The package follows semantic versioning, i.e. MAJOR.MINOR.PATCH


The SuperSaaS Python API Client is available under the MIT license. See the LICENSE file for more info.


Online bookings/appointments/calendars in Python using the SuperSaaS scheduling platform -







No packages published