Time-Based Commerce
API for Real-Time Availability & Booking

Time-based Commerce is the publishing and instant booking of services and reservable resources. Periodic makes this possible by interpreting user-defined availability information and applying business rules to create bookable time slots that can be sold just like products anywhere on the web.

We refer to the entities that offer services as Providers. Providers have a menu of bookable items to offer. Providers are usually small businesses, but they could also be schools, community groups, or even programs or events that have no physical presence at all.

Marketplaces are collections of Providers. API users who wish to create new Providers must have a Marketplace Admin account, which is associated with via a unique domain name. Providers must belong to at least one Marketplace.

To create a Marketplace account, visit http://periodic.is/launch.

API endpoint
http://periodic.is/api
Deprecation Warning
This version of the API is Deprecated

This version of the API is deprecated and will be retired at the end of 2017.

Please use the JSON-RPC API instead.

Quick-start Examples

We've put together tutorials for building some simple functions and apps. Check them out here.

Get your API key

Your API is available on the My Account page of the Periodic dashboard.

  1. Log in to the dashboard
  2. Click on the hamburger (three bars) icon in the top, right section. This should open a navigation menu.
  3. Select "My Account" - your API key is visible in the lower right section of this page

Authentication

Authentication is done with self-issued jwt tokens. You can read more about jwt at the protocol website , or in the RFC7519 draft.

A JSON Web Token (JWT) is an encoded, digitally-signed string of text that allows for secure sharing of JSON-formatted information. It consists of three sub-parts - the Header, the Payload, and the Signature - separated by periods (.). So, a typical JWT is structured like: xxxxx.yyyyy.zzzzz Each section is base64 encoded separately before joining them together with periods to form the full token.

Header

A JWT header contains information about the encoding protocol and hashing algorithm. Periodic currently only supports SHA-256 encoding, so the Header should always just be the following:

{
  "alg": "HS256",
  "typ": "JWT"
}

Base64 encoded, this is:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

so Periodic API users can always just include this string as the first part of their authentication token.

Payload

The payload contains the transmitted information. It is made up of a number of standardized "claims" - which are key-value pairs where the key is the name of claim and the value is its value. Periodic supports the following claims with the following interpretations:

iss ("issuer") - REQUIRED - at a minimum, your Marketplace name, but can also be a Provider subdomain joined to a marketplace name with a period (.).
sub ("subject") - REQUIRED - your Periodic username
iat ("issued at") - REQUIRED - the UNIX timestamp of the moment the token was created. Tokens are not valid for more than 1 minute before or after the iat value, so this should in general be the same time as the request is made.
exp ("expiration time") - OPTIONAL - the UNIX timestamp of the time after which the token is no longer valid. Overrides iat if included. (iat is nevertheless still required)
nbf ("not before") - OPTIONAL - the UNIX timestamp after which the token becomes valid. Overrides iat if included. (iat is nevertheless still required.)
jti ("jwt id") - OPTIONAL - an arbitrary, client-generated unique identifier for the claim. Inclusion is optional but strongly encouraged, as it makes tokens more secure against replay attacks. Should be a string of up to 32 characters.

Payload Example

A minimal valid payload for a Periodic authentication token:

{
  "iss": "username",
  "sub": "provider.marketplace",
  "iat": 1501768003
}

The base64-encoded string version of which would be:

eyJpc3MiOiJ1c2VybmFtZSIsInN1YiI6InByb3ZpZGVyLm1h
cmtldHBsYWNlIiwiaWF0IjoxNTAxNzY4MDAzfQ

A more comprehensive payload, including some optional claims:

{
  "iss": "username",
  "sub": "provider.marketplace",
  "iat": 1501768003,
  "nbf": 1504224000,
  "exp": 1506816000,
  "jti": "u8HhcVQkfhtwGsEmRsRP"
}

This token is valid for the entire month of September 2017, and it includes a jti unique identifier. Its base64-eocded string would be:

eyJpc3MiOiJ1c2VybmFtZSIsInN1YiI6InByb3ZpZGVyLm1hcmtldHB
sYWNlIiwiaWF0IjoxNTAxNzY4MDAzLCJuYmYiOjE1MDQyMjQwMDAsIm
V4cCI6MTUwNjgxNjAwMCwianRpIjoidThIaGNWUWtmaHR3R3NFbVJzUlAifQ

Signature

The final component of the token is the signature, which is simply the SHA-256 HMAC hash, using your API key as the secret, of the Header and Payload sections concatenated with a period. So, using the simple example from above, the header concatenated with the payload is:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ1c2VybmFtZSIsInN1YiI6InByb3ZpZGVyLm1hcmtldHBsYWNlIiwiaWF0IjoxNTAxNzY4MDAzfQ

If your API key were "secret", then the HMAC-SHA256 of this would be:

R1bcOm9SMBGqfTNZeL_7fJ3AOB5lPKgcapJEBfuoJ6A

Token

And the complete token you should send to Periodic, assuming an API key of "secret" and the simple claims object from the example is:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ1c2VybmFtZSIsInN1YiI6InByb3ZpZGVyLm1hcmtldHBsYWNlIiwiaWF0IjoxNTAxNzY4MDAzLCJuYmYiOjE1MDQyMjQwMDAsImV4cCI6MTUwNjgxNjAwMCwianRpIjoidThIaGNWUWtmaHR3R3NFbVJzUlAifQ.R1bcOm9SMBGqfTNZeL_7fJ3AOB5lPKgcapJEBfuoJ6A

Additional Documentation

You can try out more examples wit the interactive tool on the JWT homepage.

Sending a Token

Tokens should be sent via an "authorization" header. The value of the header is the string "Bearer" followed by a single space followed by the token. Continuing the previous example, it would be:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ1c2VybmFtZSIsInN1YiI6InByb3ZpZGVyLm1hcmtldHBsYWNlIiwiaWF0IjoxNTAxNzY4MDAzLCJuYmYiOjE1MDQyMjQwMDAsImV4cCI6MTUwNjgxNjAwMCwianRpIjoidThIaGNWUWtmaHR3R3NFbVJzUlAifQ.R1bcOm9SMBGqfTNZeL_7fJ3AOB5lPKgcapJEBfuoJ6A

Providers

Providers are entites that offer bookable services.

Providers are usually businesses or locations, but they can also be departments, programs or more abstract entities with no physical presence at all.

Providers make services available for booking in the form of Bookables. Bookables set the rules for how units of bookable time (timeslots) are created, and what the limits on booking them are. See the Bookable section for more details.

Providers also optionally maintain Resources. See the Resources section for details.

Required Attributes
AttributeExplanationType
nameThe name of the Provider to be displayed to end users.String
emailThe email address of the user account that will be automatically created for this provider. By default, this will double as the username for this account for the purposes of logging in to the web-based dashboard.String
firstnameThe first name of the user on the associated user account.String
lastnameThe last name of the user on the associated user account.String
subdomainThe unique (to the marketplace) subdomain that identifies the provider's bookingsite. This idenfitifer is also used as the base URL for provider-related API calls. For example, if your subdomain is myuniqesubdomain, then the URL of your bookingsite is http://myuniquesubdomain.periodic.is and API calls are made against http://myuniquesubdomain.periodic.is/apiString
Optional Attributes
AttributeExplanationType
activeIndicates whether this provider is visible to the general public.Boolean
addressThe street and number of the physical or mailing address of the Provider.String
agreementtermsText explaining the terms that customers must agree to before booking an appointment with this provider.String
blackoutsBlackouts are times/dates during which the provider is not available for booking.Array of Objects
bookablerequestenabledA flag indicating whether third parties are able to access a public-facing form for creating bookables on this provider.Boolean
bookingsitepasswordSet this if you want to require users to enter a password to access your bookingsite.String
bookingcssThe name of a less or css file with custom style alterations for your booking site.String
bookinglogoThe url of an image file of the provider's logo.String
businesshoursA specification of the normal operating hours for the provider.Object
billingstatusIndicates if the provider is in good standing with cheddar. It can have a value of either active or suspendedEnum
cityThe name of the city in which the provider is located.String
coordinatesLatLong coordinates for displaying the provider's location on the map page. This should be a list of two strings, the first of which is latitude, the second of which is longitude.Array of Strings
custommessageA tagline or description displayed to customers at the provider's bookingsite.String
datemessageThe text of the prompt on the bookingsite that asks a customer to select a date for the appointment.String
descriptionA description of the provider for internal use.String
latlongLatLong coordinates for the provider. This should be a list of two strings, the first of which is latitude, the second of which is longitude.Array of Strings
missedappointmentmessageThe text of the message sent to the provider when an appointment is marked as missed.String
nobookablesmessageThe text of the message tha displays on the bookingsite when there are no active bookables (and so it is not currently possible to book an appointment). It is useful to think of this as a 'Coming Soon' message.String
notificationsArray of objects
notificationsenabledBoolean
phoneThe provider's main phone number.String
questionsA library of questions available for inclusion in the customer form on the booking site. (See the questions section of this documentation for details.)Array
requirementgroupsA list of the Requirement Groups for this provider. (Documentation pending)Array of Objects
reservationtypesA list of the bookables associated with this provider. (See the bookable section of this documentation for details.)Array of Objects
reservationsperbookingThe maximum number of reservations a customer is allowed to book in a single session.Integer
resourceinvitemessageThe email message sent to people who have been invited to manage a resource on this provider.String
resourceholdobjectsA list of any resource holds (resources that are reserved, over a particular time range, exclusively for use on one or more designated bookables.Array of Objects
resourcesA list of the resource objects for this provider. (See the resource section of this documentation for details.)Array of Objects
stateThe state, province or locality in which this provider is located.String
submitbuttonThe text that appears in the final confirm button that the user uses to execute appointment booking on the bookingsite.String
thankyoumessageThe text displayed to a customer upon successful booking on the bookingsite. (Can be overridden by a similar bookable setting.)String
timemessageThe text of the message that prompts a customer to select a timeslot.String
timezoneA string reprsenting the time zone in which your appointments are booked.String
urlThe provider's URL.String
zipThe provider's zip or postal code.String
userinstructionsThe text of instructions provided to a user immediately upon landing on the bookingsite.String
users (DEPRECATED) A list of userids for users that have login or api access to this provider.Array of Strings
whitelabelThe name of the marketplace to which this provider belongs.String
create endpoint
curl -X POST https://YOUR_MARKETPLACE_DOMAIN/api/provider 
-d'{"name":"Provider Name", "firstname": "First", "lastname": "Last", "email": "user@mail.com", "subdomain": "mysubdomain"}'
response
 
{
  "id": "",
  "active": true,
  "address": "",
  "agreementterms": "",
  "blackouts": [...list_of_blackout_objects...],
  "bookablerequestenabled": false,
  "bookingsitepassword": "",
  "bookingcss": "",
  "bookinglogo": "",
  "displaymarketplacelogo": true,
  "drivetime": 0,
  "bookingflow": "",
  "newbusinesshours": [...availability_frames...],
  "capacityrestrictions": "",
  "city": "",
  "coordinates": [],
  "coverphoto": "",
  "custommessage": "Welcome to our booking site.",
  "datemessage": "select a date",
  "description": "",
  "dictionary": {},
  "display_extension_tos": false,
  "displaytext": {},
  "email": "user@mail.com",
  "name": "Provider Name",
  "firstname": "First",
  "gtagmanagercodeprovider": "",
  "lastname": "Last",
  "latlong": [],
  "loginenabled": false,
  "nobookablesmessage": "",
  "notifications": [...default_notification_objects...],
  "questions": [...library_of_questions_for_bookables...],
  "resourceinvitemessage": "",
  "missedappointmentmessage": "",
  "invitemessage": "",
  "phone": "",
  "website": "",
  "facebook": "",
  "twitter": "",
  "instagram": "",
  "pinterest": "",
  "regions": [],
  "reservationtypes": [...bookable_objects...],
  "requirementgroups": "",
  "reservationsperbooking": 1,
  "resources": [...resource_objects...],
  "resourceholds": [...resource_hold_objects...],
  "state": "",
  "subdomain": "mysubdomain",
  "submitbutton": "",
  "thankyoumessage": "",
  "timemessage": "",
  "timezone": "",
  "userinstructions": "",
  "url": "",
  "zip": "",
  "users": "",
  "type": "provider",
  "whitelabel": "marketplace_name",
}
retrieve endpoint
curl -X GET https://YOUR_MARKETPLACE_DOMAIN/api/provider/id/{provider_id}
response
 
{
  ...(same as above)...
}
update endpoint
curl -X PUT https://YOUR_MARKETPLACE_DOMAIN/api/provider/id/{provider_id} -d'{"name":"New Provider Name"}' 
response
 
{
  "name": "New Provider Name".
  ...(otherwise as above)...
}
destroy endpoint
curl -X DELETE https://YOUR_MARKETPLACE_DOMAIN/api/provider/id/{provider_id}
response
 
"Successfully deleted provider PROVIDER_SUBDOMAIN"
Bookables

Bookables are the services or experiences that Providers make available for booking.

Bookables may have their own Availability Frames and the following other limitations on their availability:

Bookables may optionally have associated Resources. If Resources are associated, the availability of the Bookable will be further constrained by the availability of the required Resources.

Required Attributes
AttributeExplanationType
newavailabilityA list JSON objects each representing a chunk of the recurring weekly availability of this Bookable. This includes 'startday' and 'endday' - each strings - which should be a day of the week ('monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'). Additionally, it should specify a 'starthour', 'startminute', 'startsecond', 'endhour', 'endminute', 'endsecond' - all integers representing time on a 24-hour clock. (This is not strictly required to create a bookable, however it is an integral part of definiting appointments. If not included, availability will default to 8am-5pm on weekdays.)Array of Objects
nameThe name of the Bookable to be displayed to end users.String
providerThe subdomain of the Provider to which this Bookable belongs. Can be passed via the subdomain in the URL, via the x-periodic-provider header, or as a key value pair.String
descriptionA concise description of the Bookable to be displayed to end usersString
Optional Attributes
AttributeExplanationType
addons(Advanced use) Objects that can be included with a booking to refine the experience. Addons do not affect availability, but they can affect the price or duration of an appointment.Array of Objects
addon_groups(Advanced use) Groups of addons that need to be displayed together on the bookingsite.Array of Objects
addon_stages(Advanced use) Logical groupings of related addongroups that need to be displayed together on the bookingsite.Array of Objects
approvalmodeA flag that, when set to true, requires an administrator user to approve appointments on this bookable after the customer has booked. False by default.Boolean
billinginstructionsA field to store a message about any additional information a customer may need after an appointment involving this Bookable.String
bookabletypeOne of 'standard' or 'calendarday'. ('standard' by default.) Determines whether the bookable is bookable by the day ('calendarday'), or for a custom, user-defined amount of time ('standard').String
bookinglimitThe maximum total number of reservations that can be booked on this bookable at any time. If set to 0, there is no limit (i.e. the limit is 'turned off'). Set to 0 by default.Integer
bookingmode(For advanced use.) This affects the order in which a customer is prompted for information about the appointment and is not documented here. Please contact a sales representative for more information.String
combinedslotsA flag that, when set, collapses multiple consecutive timeslots into a single, expanded reservation that starts with the earliest timeslot and ends with the latest. Basically, this is a way to allow users to book more than one timeslot in a booking.Boolean
confirmmodeA flag that, when set, requires a customer to confirm an appointment (by clicking a link sent via email) before it is fully booked. False by default.Boolean
customermaxThe maximum number of upcoming appoinments an individual customer may have on this bookable.Integer
customlinkA user-defined alias path for the bookable's directbooking siteString
downpaymentamountA currency amount that is due at the time of booking.Number
displayendFor all-day bookables (bookables with 'bookabletype' set to 'calendarday'), the time of day at which the customer is told the appointment ends. This functions like a checkout time at a hotel and is for display purposes only.String
drivetimeWhen set to a number larger than 0, before allowing a booking the system will check all reservations that fall within this number of seconds on either side of the proposed reservation and have a designated 'address' question to make sure that there is enough drive time between them. If driving from the address on any reservation to the proposed reservation's location would take longer than the time between the two appointments, the proposed reservation will be rejected.Integer
durationThe length of the appointment in seconds. Set to 3600 (1 hour) by default. Only applicable to bookables with 'bookabletype' set to 'standard.'Integer
frequencyAn interval in seconds at which appointment starttimes are generated. This is useful for generating overlapping appointment times - for example, a tour that lasts and hour but departs every 15min. In the default case, this is simply the same as the appointment duration.Number
holddurationThe number of seconds this appointment is held pending customer confirmation. Assumed to be 0 when not set.Integer
mincombinedIf 'combined' is set, this defines the minimum number of timeslots that a user must select in order to successfully book an appointment.Integer
maxcombinedIf 'combined' is set, this defines the maximum number of timeslots that a user can select for a single appointment.Integer
notificationsObject
paddingdurationThe number of seconds in down time between discrete timeslots that are available for this bookable. For example, if you specify a duration of 2700 and a paddingduration of 900, your bookable will be available every hour for 45 minutes with a 15min. break at the end of each appointment.Integer
paymenttermsInstructions to the customer conerning how to pay for this appointment - what kind of payment is due at what time using what method, etc.String
photoA URL linked to a logo/picture file for display with this bookable on the bookingsite.String
priceA currency amount that appointments involving this Bookable cost.Number
questionsSpecifications of questions that the customer will be prompted to answer upon booking an appointment involving this Bookable. This is a useful way to gather information about your customer that may be necessary to setting up the appointment.Array of objects
requiredresourcesA list of the ids of any Resources that MUST be available in order to book an appointment through this Bookable. See the Resource section of this documentation for more information about Resources.Array of Strings
requirementgroups(Advanced use.) Groups of resources, some minimum number from which must be available in order to book an appointment through this Bookable. This is not directly documented here.Array of objects
restrictionsA list of objects, each of which has a 'start' and an 'end' member, the value of which is a string in YYYY-MM-DD format indicating a start/end date. If this list is not empty, the bookable will only be available during the intervals defined by these dates.Array of Objects
seatsThe number of simultaneous or overlapping appointments that can be booked on this Bookable.Integer
seatsperbookingThe maximum number of appointments through this Bookable that a customer can book in a single session.Integer
stageselectorsArray of Objects
statusOne of 'active', 'inactive', 'archived', 'hidden'. 'Active' bookables are visible to the public. 'Inactive' bookables are temporarily disabled for booking and will not show up on the bookingsite. 'Archived' bookables are not visible on the bookingsite or dashboard but are available to be reactivated for future use. 'Hidden' bookables are available for booking but only via the directbooking link, not through the general public-facing dashboard.String
slugA user-defined unique identifier for this bookable.String
tagsKeywords associated with this Bookable. Tags enable Bookables to be grouped according to function or service for search purposes.Array of Strings
thankyoumessageA message displayed to a customer on the bookingsite when a booking is successful.String
waitlistenabledWhether or not waitlists are enabled for this bookable (false by default)Boolean
create endpoint
curl -X POST https://YOUR_PROVIDER_SUBDOMAIN.YOUR_MARKETPLACE_DOMAIN/api/bookable -d'{"name":"Bookable Name"}' 
response
 
 {
   "addons": [...list_of_addon_objects...]
   "addon_groups": [...list_of_addon_groups...]
   "addon_stages": [...list_of_addon_stages...]
   "approvalmode": false,
   "billinginstructions": "",
   "bookabletype": "standard",
   "bookinglimit": 0,
   "confirmmode": false,
   "combinedslots": false,
   "contactenabled": false,
   "customermax": 0,
   "customlink": "",
   "description": "",
   "displayend": "",
   "downpaymentamount": 0,
   "drivetime": 0,
   "duration":3600,
   "frequency": 0,
   "mincombined": 1,
   "maxcombined": 1,
   "name": "Bookable Name",
   "newavailability":[...list_of_availability_frames..],
   "notifications":[...list_of_notification_objects...],
   "holdduration": 0,
   "paddingduration": 0,
   "downpaymentamount": 0,
   "paymentterms": "",
   "photo": "photourl",
   "price": 0,
   "questions": [...list_of_customer_questions...],
   "requiredresources":[...list_of_resource_ids...],
   "requirementgroups":[...list_of_requirementgroup_objects...],
   "restrictions":[...list_of_restriction_objects...],
   "seats": 1,
   "seatsperbooking": 1,
   "slug": "bookable_slug",
   "status": "active",
   "tags": [],
   "thankyoumessage": "",
   "timeslots": [...list_of_pregenerated_recurring_timeslots...],
   "type": "bookable",
   "provider":"providersubdomain",
   "id":"bookable_id"
   "whitelabel": "marketplace_name" 
 }
retrieve endpoint
curl -X GET https://YOUR_PROVIDER_SUBDOMAIN.YOUR_MARKETPLACE_DOMAIN/api/bookable/id/BOOKABLE_ID 
response
 
{
  ...(same as above)...
}
update endpoint
curl -X PUT https://YOUR_PROVIDER_SUBDOMAIN.YOUR_MARKETPLACE_DOMAIN/api/bookable/id/BOOKABLE_ID -d'{"name":"New Bookable Name"}' 
response
 
{
  "name": "New Bookable".
  ...(otherwise as above)...
}
delete endpoint
curl -X DELETE https://YOUR_PROVIDER_SUBDOMAIN.YOUR_MARKETPLACE_DOMAIN/api/bookable/id/BOOKABLE_ID 
response
 
"Successfully deleted bookable BOOKABLE_ID"
Resources

Resources are people, objects, or facilities who affect the availability of a Bookable in some way. For example, if the Bookable defines a lecture or class that the public can sign up to attend, its associated Resources might be things like a classrooms and a teacher - things without which the lecture cannot take place.

Each Resource can be associated with multiple Resource Groups, which can be used when more than one Resource is capable of fulfilling the service. Resource Groups can be used to provide options to customers, or to take advantage of periodic's automatic assignment to programatically distribute reservations among similar Resources. For example, a barbershop might create a Resource Group containing all of the barbers in the shop. Reservations can automatically be assigned to a barber based on a defined priority order, or customers can be prompted to choose a barber from the group. Bookables can require any number of Resources in a group to be available in order for a Reservation to take place.

Required Attributes
AttributeExplanationType
nameThe name for this Resource.String
providerThe subdomain of the Provider with which this Resource is associated with.String
Optional Attributes
AttributeExplanationType
newavailabilityA list JSON objects each representing a chunk of the recurring weekly availability of this Resource. This includes 'startday' and 'endday' - each strings - which should be a day of the week ('monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'). Additionally, it should specify a 'starthour', 'startminute', 'startsecond', 'endhour', 'endminute', 'endsecond' - all integers representing time on a 24-hour clock. (This is not strictly required to create a bookable, however it is an integral part of defining appointments. If not included, availability will default to 8am-5pm on weekdays.)Array of Objects
activeWhether this Resource is available for booking.Boolean
descriptionA description of this resource.String
slugA user-defined unique identifier for this Resource.String
locationStore lat long coordinates of the resourceObject
photoUrl of an image file of the resourceString
timezoneA string representing the time zone in which your resource is located.String
whitelabelThe name of the marketplace to which this resource belongs.String
reservation_capacityThe total number of seats for overlapping reservations that can be booked on this resource. In the default case, this is equivalent to the total number of overlapping reservations that can be booked on this resource.Integer
value_capacityThe total number of value points for overlapping reservations that can be booked on this resourceInteger
allowcustomerinvitationsEnables customers that book the resource to be added as attendees on calendar events created on 3rd party calendars services like google or outlook. The resource must be connected to a 3rd party calendar serviceBoolean
create endpoint
curl -X POST https://YOUR_PROVIDER_NAME.YOUR_MARKETPLACE_DOMAIN/api/resource -d'{"name":"Resource Name"}'
response
 
 {
   "active": true,
   "description": "",
   "name": "Resource Name",
   "newavailability":[...list_of_availability_frames..],
   "photo":"",
   "slug":"resource_name",
   "timezone":"",
   "type":"resource",
   "provider":"providersubdomain",
   "id":"resource_id"
   "whitelabel": "marketplace_name" 
 }
retrieve endpoint
curl -X GET https://YOUR_PROVIDER_SUBDOMAIN.YOUR_MARKETPLACE_DOMAIN/api/resource/id/RESOURCE_ID 
response
 
{
  ...(same as above)...
}
update endpoint
curl -X PUT https://YOUR_PROVIDER_NAME.YOUR_MARKETPLACE_DOMAIN/api/resource/id/RESOURCE_ID  -d'{"name":"New Resource Name"}'
response
 
 {
   "name": "New Resource Name",
  ...(otherwise as above)...
 }
destroy endpoint
curl -X DELETE https://YOUR_PROVIDER_NAME.YOUR_MARKETPLACE_DOMAIN/api/resource/id/RESOURCE_ID
response
 
"Successfully deleted resource RESOURCE_ID"
Availability

Availability is the one entity in our API that does not correspond neatly with a REST protocol. Availability is used to retrieve TimeSlots during which a Bookable can be booked. For Bookables with Resource requirements, the returned TimeSlot objects will each contain an array of Resources available to be booked.

Calls to Availability are all GET calls to /availability, with the rest of the endpoint consisting of key-value pairs added to the regular url. At a minimum, the start, end and bookable parameters are required. So, a minimal endpoint for /availability would be:

/availability/start/2017-09-01%2013:00:00/end/2017-09-02%2013:00:00/bookable/1

This call asks for all timeslots between 1pm 1 September and 1pm 2 September 2017 for a bookble with id 1. (For this call to work, it would of course be necessary to include the provider subdomain in the url.). Parameters can appear in any order in the URL provided that each recognized key is followed by an value. A list of acceptable keys and their expected value types is as follows:

Required Attributes
AttributeExplanationType
bookableThe id of the bookable whose availability is being queried. (Note: it is possible to query availability for resources without including a bookable, but not through this call. Documentation for other type of availability calls will be releaseed shortly.)String
startA datetime string in format YYYY-MM-DD HH:mm:ss defining the start of the timespan over which availability is being queried.Datetime String
endA datetime string in format YYYY-MM-DD HH:mm:ss defining the end of the timespan over which availability is being queried.Datetime String
Optional Attributes
AttributeExplanationType
resourcesA comma-separated list of resource ids to confine the search toComma-separated String
tagsA comma-separated list of tags of bookables accross providers to searchComma-separated String
retrieve endpoint
 
curl -X GET https://YOUR_PROVIDER_SUBDOMAIN.YOUR_MARKETPLACE_DOMAIN/availability/start
/2017-09-01%2013:00:00/end/2017-09-02%2015:00:00/bookable/1/resources/1,2,3
response
 
[{
  "start": "2017-09-01 13:00:00"
  "end": "2017-09-01 14:00:00"
  "bookable": "1"
  "resources": ["1", "2"], 
  "seats_available": 1
},
{
  "start": "2017-09-01 14:00:00"
  "end": "2017-09-01 15:00:00"
  "bookable": "1"
  "resources": ["3"], 
  "seats_available": 1
}]
Reservations

When a Reservation is created, the associated Bookable and optionally associated Resources are held for the associated Customer. Except when a Bookable allows multiple seats, or when associated Resources have a defined capacity, the associated Resources will no longer be available during the Reservation's time frame.

Reservations are always associated with a Customer. If a Reservation is created without an associated Customer, a Customer record will automatically be created using the First Name, Last Name, and email address submitted.

Required Attributes
AttributeExplanationType
bookableThe id of the Bookable this reservation is booked through.string
endA datetime string in YYYY-MM-DD HH:mm:ss format indicating when the reservation ends.string
providerSubdomain of the provider you want to create a reservation onstring
startA datetime string in YYYY-MM-DD HH:mm:ss format indicating when the reservation begins.string
whitelabelThe name of the marketplace to which this reservation belongs.string
userThe id of the user who booked this reservation (this will be automatically generated by the system if the optional customquestions object is included and contains questions for First Name, Last Name and Email, which are required on all Bookables).string
Optional Attributes
AttributeExplanationType
checkedinA datetime string in YYYY-MM-DD HH:mm:ss format indicating when the customer checked in.string
checkedoutA datetime string in YYYY-MM-DD HH:mm:ss format indicating when the customer checked out.string
commentsComments for internal use about this reservation.string
customquestionsA list of objects representing answer supplied to questions included on the customer form on the bookingsite.array of objects
discountcodeIf a discountcode was redeemed in paying for this reservation, it should be noted here.String
expiresA datetime string in YYYY-MM-DD HH:mm:ss format indicating when the reservation need no longer be counted for calculating availability - i.e. when the reservation is no longer active. For the vast majority of cases, this will be the same as the required end parameter. This can be used to manually set a temporary hold on a reservation.string
emailEmail of the user who booked this reservationstring
holdThe number of seconds this reservation is being held for. If specified, 'expires' will be automatically set to the datetime string corrsponding to this many seconds in the future from the time of booking.integer
locationStore lat long coordinates of the reservation, address type custom question response is converted to lat longobject
mobile_phone_numberMobile number of the user who booked this reservationstring
paymentinformationStore payment related information on the reservationobject
resourcesA list of id of resources being booked for use during this Reservation.array of strings
statusA string indicating the current status of the Reservation. It is primarily used internally to mark a reservation as cancelled without deleting it from the database (for recordkeeping purposes). A reservation can be cancelled by simply setting this to 'cancelled.'string
seatsThe number of seats the reservation accounts forinteger
valueSome resources have a 'value_capacity' score that, when exceeded by a reservation, disallows the use of that resource for the reservation in question. The 'value' component of a reservation is the number that is used to compare against the resource's 'value_capacity'. It is set in conjunction with user responses to form question. This property is for advanced use only.integer
waitlistpositionWhat position on the waitlist (if enabled for the bookable) this reservation occupiesinteger
create endpoint
curl -X POST https://YOUR_PROVIDER_SUBDOMAIN.YOUR_MARKETPLACE_DOMAIN/api/reservation 
-d'{"start":"2017-08-04 13:00:00", "end": "2017-08-04 14:00:00", "bookable": "bookable_id", 
"resources": [...list_of_resource_ids...], "first_name": "First", "last_name": "Last", 
"email": "user@mail.com", "questions": [...list_of_response_objects...], "user": "user_id"}'
response
 
{
  "bookable": "bookable_id",
  "comments": "",
  "customquestions": [...list_of_response_objects...],
  "email": "user@mail.com",
  "end": "2017-08-04 14:00:00",
  "expires": "2017-08-04 14:00:00",
  "first_name": "First",
  "hold": 0,
  "last_name": "Last",
  "location": "",
  "mobile_phone_number": "",
  "networkuser": "",
  "packaged_bookables": "",
  "package_id": "",
  "package_type": "",
  "phone": "",
  "provider": "providersubdomain",
  "paymentinformation": "",
  "resources": [...list_of_resource_ids...],
  "seats": 1,
  "start": "2017-08-04 13:00:00",
  "status": "booked",
  "user": "user_id",
  "type": "reservation",
  "whitelabel": "marketplace_name"
}
cancel endpoint
curl -X PUT https://YOUR_PROVIDER_SUBDOMAIN.YOUR_MARKETPLACE_DOMAIN/api/reservation/cancel/id/RESERVATION_ID
response
 
"Successfully cancelled reservation RESERVATION_ID"
Users

Users are the individuals who are able to access your Marketplace via the dashboard and the API. Users can have one of several available roles, each of which give the user permission to execute a different set of functions.

Admin Users have full access to all functions within your Marketplace. Provider Users are limited to a specified Provider. Employee Users are able to create and modify Reservations for their associated Provider, but they are not able to create or modify Bookables or Resources. Employee Users can optionally be associated with a list of Resources. An Employee User who is associated with a single Resource is assumed to be a Resource User. Resource Users can only create and modify reservations for their Resource and edit the profile and availability of their Resource.

Required Attributes
AttributeExplanationType
firstnameThe user's first name.String
lastnameThe user's last name.String
emailThe user's email address.String
passwordThe login password for the web interface.String
roleOne of 'admin', 'provider', 'associate' or 'employee'. This specifies the level of access this user is granted.String
slugA user-defined unique identifier for the user. This is also used as the login to the user interface. It defaults to the email address entered.String
Optional Attributes
AttributeExplanationType
apikeyThe unique API access key generated by Periodic for this user.String
avatarA url pointing to an avatar for the user.Url
address1The second line of the user's contact addressString
address2The second line of the user's contact addressString
cityThe city associated with the user's contact addressString
networkidAn optional networkid associated with this account in a thrid-party integration.Strings
providersThe subdomains of the providers to which this user is granted access.Array of Strings
stateA state, provice, or other administrative regionString
resourcesA list of the ids of resources this user is allowed to manageArray of Strings
zipA zip/postal code for the userString
countryCountry of the userString
providerThe subdomain of the primary provider for this user (if applicable).String
whitelabelThe name of the marketplace to which this user belongs.String
create endpoint
curl -X POST https://YOUR_PROVIDER_SUBDOMAIN.YOUR_MARKETPLACE_DOMAIN/api/user 
-d'{"firstname":"First", "lastname": "Last", "role": "provider", "email": "user@mail.com", "password": "password"}'
response
 
{
  "avatar": "",
  "firstname": "First",
  "id": "user_id",
  "lastname": "Last",
  "email": "user@mail.com",
  "slug": "user@mail.com",
  "apikey": "user_api_key",
  "networkid": "",
  "address1": "",
  "address2": "",
  "city": "",
  "state": "",
  "zip": "",
  "resources": [...list_of_associated_resources...],
  "role": "provider",
  "providers": [],
  "whitelabels": [],
  "type": "user",
  "whitelabel": "marketplace_name",
}
retrieve endpoint
curl -X GET https://YOUR_PROVIDER_SUBDOMAIN.YOUR_MARKETPLACE_DOMAIN/api/user/id/USER_ID 
response
 
{
 ...(same as above)...
}
update endpoint
curl -X PUT https://YOUR_PROVIDER_SUBDOMAIN.YOUR_MARKETPLACE_DOMAIN/api/user/id/USER_ID 
-d'{"firstname":"New"}'
response
 
{
  "firstname": "New",
 ...(otherwise as above)...
}
destroy endpoint
curl -X DELETE https://YOUR_PROVIDER_SUBDOMAIN.YOUR_MARKETPLACE_DOMAIN/api/user/id/USER_ID
response
 
  "Successfully deleted user USER_ID"