Events (Bookings)¶
see https://sls-api.sheepcrm.com/.well-known/docs.html for v2 events API
Note
Events were previously known in the system as bookings the data type name is still booking
Recommended minimum fields:
- title
name of the booking
- description
long text for the booking description
- start_date
start date of the event, most date types supported
- end_date
end date of the event, most date types supported
- start_time
start time of the event HH:MM
- end_time
end time of the event HH:MM
- booking_type
string - use to group bookings of a certain type on a calendar
Additional fields:
- location
location string, typically building name or place
- location_address_string
location address string, use commas to separate multiple lines
- location_postal_code
zip or post code of the location
- location_country
location country
- website
an externally event web site
- external_web_link
an externally event web link to a booking / purchase page
- external_image
an externally hosted image for the event
- hide_from_self_service
boolean to control showing the event with the sheepApp
- member_only_event
boolean to limit purchase of event tickets to members
- has_available_tickets
boolean to indicate available
- is_sold_out
boolean to indicate sold out - use in conjunction with has_available_tickets
- maximum_ticket_price
upper price for tickets - used to show price range
- minimum_ticket_price
lower price for tickets - used to show price range
- start_sales_date
date when tickets will be available from
- waitlist_available
boolean to show if a waiting list is available
- eventbrite_id
string - the Eventbrite UID for the event (when event is controlled by Eventbrite)
- use_access_code
boolean - Eventbrite control field
- controller
string - which system is controlling the event e.g. Eventbrite, Ticketsolve, CraftEvents, sheepCRM
- lifecycle_emails
boolean - turn on lifecycle emails for this booking
Getting events¶
The version 2 API is recommended for read access to event listings. Series of events are collapsed into a since record (the most recent within the date range). current is defined as events from the last couple of weeks and falling within the next few months. running events are those happening at the time (end date > now > start date)
Note
Events service endpoint has changed from https://sls-api.sheepcrm.com/api/v2/ to https://sls-api.sheepcrm.com/events/v2/
Note
see https://sls-api.sheepcrm.com/events/v2/api-docs/html for full V2 Docs
http https://api.sheepcrm.com/api/v1/$FLOCK/booking/ "Authorization: Bearer $API_KEY" sort=="-start_date" series_id=="S018"
Create a new event¶
Recommended end point - using booking definitions
Required fields:
- title
name of the booking
- start_date
start date of the event, most date types supported
- start_time
start time of the event HH:MM
- booking_defn
reference - the URI of the booking definition
Optional fields:
- end_time
end time of the event HH:MM
- end_date
end date of the event, most date types supported
- group
reference - the URI of the group
http POST https://api.sheepcrm.com/api/v1/$FLOCK/events/ title="my new booking" start_date="2022-01-17" start_time="10:23" booking_defn=/example/booking_defn/610d1c5feb69265309cf6cb2/ "Authorization: Bearer $API_KEY"
Original/standard endpoint
http POST https://api.sheepcrm.com/api/v1/$FLOCK/booking/ Authorization:"Bearer $API_KEY"
Accept a event enquiry¶
http PUT https://api.sheepcrm.com/api/v1/$FLOCK/booking/5faa709180859e1f88d765e4/accept/ Authorization:"Bearer $API_KEY"
Reject a event enquiry¶
http PUT https://api.sheepcrm.com/api/v1/$FLOCK/booking/5faa709180859e1f88d765e4/reject/ Authorization:"Bearer $API_KEY"
Cancel a event¶
http PUT https://api.sheepcrm.com/api/v1/$FLOCK/booking/5faa709180859e1f88d765e4/cancel/ Authorization:"Bearer $API_KEY"
Uncancel a event¶
http PUT https://api.sheepcrm.com/api/v1/$FLOCK/booking/5faa709180859e1f88d765e4/uncancel/ Authorization:"Bearer $API_KEY"
Enable stock control¶
http PUT https://api.sheepcrm.com/api/v1/example/booking/5faa709180859e1f88d765e4/ ticket_stock_control=True "Authorization: Bearer $API_KEY"
Check ticket stock¶
http https://api.sheepcrm.com/api/v1/example/booking/5faa709180859e1f88d765e4/ticket_stock/ "Authorization: Bearer $API_KEY"
HTTP/1.1 200 OK
{
"errors": [],
"skus": {
"total_available": 0
}
}
Example with one ticket type¶
http https://api.sheepcrm.com/api/v1/example/booking/5faa709180859e1f88d765e4/ticket_stock/ "Authorization: Bearer $API_KEY"
HTTP/1.1 200 OK
{
"errors": [],
"skus": {
"/example/ticket_type/56d5c3fb3078f80d1dbd896b/": {
"allocated": 2,
"amount": "12.00",
"available": 18,
"available_from_date": {},
"currency": "gbp",
"description": " ",
"name": "Standard",
"next_available": [
"/example/sku/61b9bb27683e8011b976a00c/",
"/example/sku/61b9bb27683e8011b976a00d/",
"/example/sku/61b9bb27683e8011b976a00e/",
"/example/sku/61b9bb27683e8011b976a00f/",
"/example/sku/61b9bb27683e8011b976a010/",
"/example/sku/61b9bb27683e8011b976a011/",
"/example/sku/61b9bb27683e8011b976a012/",
"/example/sku/61b9bb27683e8011b976a013/",
"/example/sku/61b9bb27683e8011b976a014/",
"/example/sku/61b9bb27683e8011b976a015/"
],
"number_of_attendees_per_ticket": "1",
"pricing": "full_price",
"reserved": 0,
"single_use": null,
"tags": [],
"tax": "standard"
},
"total_available": 19
}
}
Create stock for an event¶
Required fields:
- ticket_type
the URI of the ticket type
- quantity
ticket quantity (limited to 250 per API call)
Optional fields:
- available_from_date
stock is only available for use after this date - default is None / no date
- available_until_date
stock is only available until this date - default is None / no date
http POST https://api.sheepcrm.com/api/v1/example/booking/5faa709180859e1f88d765e4/ticket_stock/ ticket_type=/example/ticket_type/56d5c3fb3078f80d1dbd896b/ quantity=25 "Authorization: Bearer $API_KEY"
HTTP/1.1 201 OK
{
"errors": [],
"skus": {
"/example/ticket_type/56d5c3fb3078f80d1dbd896b/": {
"allocated": 0,
"available": 25,
"reserved": 0
},
"total_available": 0
}
}
Remove ticket stock¶
Required fields:
- ticket_type
the URI of the ticket type
- quantity
ticket quantity
Not stock that has been allocated or reserved cannot be removed.
http DELETE https://api.sheepcrm.com/api/v1/example/booking/5faa709180859e1f88d765e4/ticket_stock/ ticket_type=/example/ticket_type/56d5c3fb3078f80d1dbd896b/ quantity=5 "Authorization: Bearer $API_KEY"
HTTP/1.1 200 OK
{
"errors": [],
"skus": {
"/example/ticket_type/56d5c3fb3078f80d1dbd896b/": {
"allocated": 0,
"available": 20,
"available_from_date": {},
"deleted": 5,
"next_available": [
"/example/sku/61b9bb27683e8011b976a005/",
"/example/sku/61b9bb27683e8011b976a006/",
"/example/sku/61b9bb27683e8011b976a007/",
"/example/sku/61b9bb27683e8011b976a008/",
"/example/sku/61b9bb27683e8011b976a009/",
"/example/sku/61b9bb27683e8011b976a00a/",
"/example/sku/61b9bb27683e8011b976a00b/",
"/example/sku/61b9bb27683e8011b976a00c/",
"/example/sku/61b9bb27683e8011b976a00d/",
"/example/sku/61b9bb27683e8011b976a00e/"
],
"reserved": 0
},
"total_available": 25
}
}
Allocate a ticket from stock¶
Required fields:
- ticket_type
the URI of the ticket type
- buyer
the URI of the ticket buyer
Optional fields:
- quantity
ticket quantity, default = 1
http POST https://api.sheepcrm.com/api/v1/example/booking/5faa709180859e1f88d765e4/allocate_ticket_from_stock/ ticket_type=/example/ticket_type/56d5c3fb3078f80d1dbd896b/ buyer=/example/person/5ff0c404cd59d5159d426aed/ "Authorization: Bearer $API_KEY"
HTTP/1.1 200 OK
{
"stock": [
"/example/sku/61b9bb27683e8011b976a00a/"
],
"ticket": "/example/ticket/61b9c226683e8011bd76a078/"
}
Return a ticket to stock¶
http POST https://api.sheepcrm.com/api/v1/example/ticket/5faa709180859e1f88d765e4/return_to_stock/ "Authorization: Bearer $API_KEY"
HTTP/1.1 200 OK
{
"stock": [
"/example/sku/61b9bb27683e8011b976a00a/"
],
"ticket": "/example/ticket/61b9c226683e8011bd76a078/"
}
Event series¶
Where a series of events is needed a series can be created.
View events in a series¶
http GET https://api.sheepcrm.com/api/v1/example/booking/5faa709180859e1f88d765e4/series/ "Authorization: Bearer $API_KEY"
HTTP/1.1 200 OK
{
"errors": [],
"series_bookings": [
{
"end_datetime": "2019-02-06T14:30:00",
"series_counter": 1,
"start_datetime": "2019-02-06T13:00:00",
"status": "new",
"title": "--booking--title",
"uri": "/example/booking/5faa709180859e1f88d765e4/"
},
{
"end_datetime": "2019-02-07T14:30:00",
"series_counter": 2,
"start_datetime": "2019-02-07T13:00:00",
"status": "new",
"title": "--booking--title",
"uri": "/example/booking/61bb2b1b9d13ab37fbb93225/"
},
{
"end_datetime": "2019-02-08T14:30:00",
"series_counter": 3,
"start_datetime": "2019-02-08T13:00:00",
"status": "new",
"title": "--booking--title",
"uri": "/example/booking/61bb2c259d13ab396102c18b/"
},
{
"end_datetime": "2019-02-09T14:30:00",
"series_counter": 4,
"start_datetime": "2019-02-09T13:00:00",
"status": "new",
"title": "--booking--title",
"uri": "/example/booking/61bb2c269d13ab396102c19b/"
}
],
"series_id": "bcd0e1c3f3"
}
Create a series¶
A series is simply one base event repeated with differnt dates. The base event should be setup as required with all appropriate fields set. When the base event has been fully configured it can be repeated. All the event data fields will be copied onto the new events.
Required fields:
- repeat
daily, weekly, monthly - contact our team to request other repeating sequences
Optional fields:
- number_of_events
how many events in the series
- until
repeat events until this date (exclusive)
Series are limited to 2 years or 100 events
http POST https://api.sheepcrm.com/api/v1/example/booking/5faa709180859e1f88d765e4/series/ "Authorization: Bearer $API_KEY" number_of_events=3 repeat=daily
HTTP/1.1 200 OK
{
"errors": [],
"series_bookings": [
{
"end_datetime": "2019-02-06T14:30:00",
"series_counter": 1,
"start_datetime": "2019-02-06T13:00:00",
"status": "new",
"title": "--booking--title",
"uri": "/example/booking/5faa709180859e1f88d765e4/"
},
{
"end_datetime": "2019-02-07T14:30:00",
"series_counter": 2,
"start_datetime": "2019-02-07T13:00:00",
"status": "new",
"title": "--booking--title",
"uri": "/example/booking/61bb2b1b9d13ab37fbb93225/"
},
{
"end_datetime": "2019-02-08T14:30:00",
"series_counter": 3,
"start_datetime": "2019-02-08T13:00:00",
"status": "new",
"title": "--booking--title",
"uri": "/example/booking/61bb2c259d13ab396102c18b/"
},
{
"end_datetime": "2019-02-09T14:30:00",
"series_counter": 4,
"start_datetime": "2019-02-09T13:00:00",
"status": "new",
"title": "--booking--title",
"uri": "/example/booking/61bb2c269d13ab396102c19b/"
}
],
"series_id": "bcd0e1c3f3"
}
Delete from a series¶
Required fields:
- delete
all - delete all bookings in series including this booking following - delete all bookings after this event in the series, including this booking
http DELETE https://api.sheepcrm.com/api/v1/example/booking/5faa709180859e1f88d765e4/series/ "Authorization: Bearer $API_KEY" delete=following|all
HTTP/1.1 200 OK
{
"deleted": [
"/example/booking/5faa709180859e1f88d765e4/"
],
"errors": [],
"remaining": [
"/example/booking/5c4b9987049057256a3e1c6d/",
"/example/booking/61bb36b59d13ab41c22116f7/",
"/example/booking/61bb36b59d13ab41c2211707/"
],
"series_id": "bcd0e1c3f3"
}
Remove a single event from a series¶
http DELETE https://api.sheepcrm.com/api/v1/example/booking/5faa709180859e1f88d765e4/delete_from_series/ "Authorization: Bearer $API_KEY"
HTTP/1.1 200 OK
{
"status": "ok"
}
Extend a series¶
Series can be extended from the end, the repeat gap is determined by the existing series.
- number_of_events
how many events to add to the series
- until
repeat events until this date (exclusive)
http PUT https://api.sheepcrm.com/api/v1/example/booking/5faa709180859e1f88d765e4/series/ "Authorization: Bearer $API_KEY" number_of_events=2