NAV
curl

Introduction

API Endpoint:

https://api.bookwhen.com/v1

Welcome to the Bookwhen Public API docs.

Bookwhen is a flexible booking system for recurring events such as classes, courses, and workshops. This API is used by the public pages to list events and take bookings. Contact support@bookwhen.com to make a request for additional resources.

Authentication

Use HTTP Basic authentication for all requests:

curl https://api.bookwhen.com/v1/events \
  -u 8itj6o2stks9r5u7mhy742g3fb4g:

Replace 8itj6o2stks9r5u7mhy742g3fb4g with your API Key. Append a colon : to prevent it from asking for a password.

All requests must be authenticated using an HTTP Basic username and a blank password.

The username must contain the API Key for your account, and optionally an OAuth2 bearer token obtained for a particular user. Join the two tokens with a hyphen.

You will soon be able to obtain your API Key from your account settings pages, but for now please get in touch.

Example of a call authenticated additionally with an OAuth2 bearer token:

curl https://api.bookwhen.com/v1/events \
  -u 8itj6o2stks9r5u7mhy742g3fb4g-f22031c16c985ef9e50ab04c5f5c1bf318bb9848cddbdd7dca26dd426a0f2cc1:

Note: The use of the OAuth2 bearer token embedded in the basic auth username is a little unconventional but ‘keeps it simple’.

The OAuth2 endpoints are:

http://api.bookwhen.com/oauth/authorize http://api.bookwhen.com/oauth/token

Contact us to set you up with an OAuth2 client ID and secret.

People

Get Authenticated User

curl https://api.bookwhen.com/v1/people/current \
  -u 8itj6o2stks9r5u7mhy742g3fb4g-f22031c16c985ef9e50ab04c5f5c1bf318bb9848cddbdd7dca26dd426a0f2cc1:
{
  "person": {
    "id": "11wgzy8pycii",
    "username": "test",
    "email": "test@example.com",
    "is_admin": false
  }
}

Retrieve basic information about the current user as authenticated by the OAuth token. If no OAuth2 bearer token is supplied then a 404 person not found message will be returned.

HTTP Request

GET https://api.bookwhen.com/v1/people/current

Attributes

Attribute Description
is_admin Is the user an administrator of the account?

Events

Get All Events

curl https://api.bookwhen.com/v1/events?calendar=5tsd78lwht6g&limit=2&offset=0 \
  -u 8itj6o2stks9r5u7mhy742g3fb4g:

The above command returns JSON structured like this:

{
  "events": [
    {
      "id": "ev-sv06-20151204100000",
      "title": "Friday workshop",
      "start_at": "2015-12-04T10:00:00.000+00:00",
      "end_at": "2015-12-04T12:30:00.000+00:00",
      "all_day": false,
      "attendee_limit": 12,
      "attendee_count": 1,
      "ticket_ids": [
        "ti-sv06-20151204100000-tqn6",
        "ti-sv06-20151204100000-t3cm",
        "ti-sv06-20151204100000-tvqe"
      ]
    },
    {
      "id": "ev-sgw7-20151205130000",
      "title": "Saturday session",
      "start_at": "2015-12-05T13:00:00.000+00:00",
      "end_at": "2015-12-05T14:00:00.000+00:00",
      "all_day": false,
      "attendee_limit": 1,
      "attendee_count": 0,
      "ticket_ids": [
        "ti-sgw7-20151205130000-t2mm"
      ]
    }
  ],
  "meta": {
    "continues": true
  }
}

This endpoint retrieves all events.

HTTP Request

GET https://api.bookwhen.com/v1/events

Query Parameters

Parameter Description
calendar Restrict to events on a given calendar. The calendar ID can be found in the URL of your admin schedule page.
entry Restrict to a single entry type.
limit Max records to return. Default 20.
offset Offset starting point in list of items.
starts Dictionary: gt (>), gte (>=), lt (<), lte (<=)
tags Array of tag words to include. All if blank.
locations Array of location IDs to include. All if blank.
search_text Free text search on title and description.

Get a Specific Event

curl https://api.bookwhen.com/v1/events/ev-sv06-20151204100000 \
  -u 8itj6o2stks9r5u7mhy742g3fb4g:

The above returns JSON structured like this:

{
  "event": {
    "id": "ev-sv06-20151204100000",
    "title": "Friday workshop",
    "details": "Ongoing event for the gathering of all interested parties. Please register your interest. Numbers are limited.",
    "start_at": "2015-12-04T10:00:00.000+00:00",
    "end_at": "2015-12-04T12:30:00.000+00:00",
    "all_day": false,
    "attendee_limit": 12,
    "attendee_count": 1,
    "waiting_list": true,
    "reserved_for_waiting_list": false,
    "location_id": "sjm7pskr31t3",
    "attachment_ids": [
      "ezwuw3t788kf"
    ],
    "ticket_ids": [
      "ti-sv06-20151204100000-tqn6",
      "ti-sv06-20151204100000-t3cm",
      "ti-sv06-20151204100000-tvqe"
    ]
  },
  "locations": [
    {
      "id": "sjm7pskr31t3",
      "address_text": "Buckingham Palace\r\nLondon",
      "additional_info": "",
      "latitude": 51.5006426992722,
      "longitude": -0.140173386230458,
      "zoom": 15,
      "map_url": "https://bkwn.s3.amazonaws.com/maps/amplt327zhcc/sjm7pskr31t3/staticmap.png"
    }
  ],
  "attachments": [
    {
      "id": "ezwuw3t788kf",
      "title": "Example document",
      "file_name": "pdf-sample.pdf",
      "file_url": "https://amazonaws.com/attachments/...",
      "file_size_bytes": "7945",
      "file_size_text": "7.76 KB",
      "file_type": "pdf",
      "content_type": "application/pdf"
    }
  ],
  "events": [
    {
      "id": "ev-sv06-20151204100000",
      "title": "Friday workshop",
      "start_at": "2015-12-04T10:00:00.000+00:00",
      "end_at": "2015-12-04T12:30:00.000+00:00",
      "all_day": false,
      "attendee_limit": 12,
      "attendee_count": 1,
      "ticket_ids": [
        "ti-sv06-20151204100000-tqn6",
        "ti-sv06-20151204100000-t3cm",
        "ti-sv06-20151204100000-tvqe"
      ]
    }
  ],
  "tickets": [
    {
      "id": "ti-sv06-20151204100000-tqn6",
      "title": "Standard booking",
      "details": "",
      "number_taken": 0,
      "basket_limit": 10,
      "group_ticket": false,
      "available_from": "2015-09-05T10:00:00.000+01:00",
      "available_to": "2015-12-03T10:00:00.000+00:00",
      "event_ids": [
        "ev-sv06-20151204100000"
      ],
      "cost": {
        "currency_code": "GBP",
        "net": 500,
        "tax": 100
      }
    },
    {
      "id": "ti-sv06-20151204100000-t3cm",
      "title": "New membership",
      "details": "Standard booking plus new membership (only £40 for the year)",
      "number_taken": 0,
      "basket_limit": 10,
      "group_ticket": false,
      "available_from": "2015-09-05T10:00:00.000+01:00",
      "available_to": "2015-12-03T10:00:00.000+00:00",
      "event_ids": [
        "ev-sv06-20151204100000"
      ],
      "cost": {
        "currency_code": "GBP",
        "net": 4500,
        "tax": 900
      }
    },
    {
      "id": "ti-sv06-20151204100000-tvqe",
      "title": "Member's booking",
      "details": "This incurs no charge but your membership card must be presented on entry.",
      "number_taken": 1,
      "basket_limit": 10,
      "group_ticket": false,
      "available_from": "2015-09-05T10:00:00.000+01:00",
      "available_to": "2015-12-03T10:00:00.000+00:00",
      "event_ids": [
        "ev-sv06-20151204100000"
      ]
    }
  ]
}

This endpoint retrieves a specific event.

HTTP Request

GET http://example.com/events/<ID>

URL Parameters

Parameter Description
ID The ID of the event to retrieve