| title | Bookings |
|---|---|
| nav_order | 2 |
| Name | Type | Description |
|---|---|---|
| id | Integer | Automatically set |
| created_at | Datetime | Automatically set |
| updated_at | Datetime | Automatically set |
| service_id | Integer | Not required |
| event_id | Integer | Not required |
| resource_id | Integer | Required |
| person_id | Integer | Not required |
| booked_from | Datetime | Required |
| booked_to | Datetime | Required |
| expires_at | Datetime | Not required |
| title | String | Not required |
| notes | Text | Not required |
| reminder_at | Datetime | Not required |
| reminded_at | Datetime | Not required |
| paid_at | Datetime | Not required |
| external_id | String | Not required |
| paid_amount | Decimal | Not required |
| revision_count | Integer | Automatically set |
| created_by | String | Automatically set |
| updated_by | String | Automatically set |
| external_url | String | Not required |
| external_host_url | String | Not required |
| booked_by_person_id | Integer | Not required. Person who made the booking (e.g. parent booking for child). |
| verification_method | String | Only for output. |
| location_url | String | Only for output. |
| location_host_url | String | Only for output. |
| custom_data | Array | Not required |
| state | String | Automatically set. See states |
| active | Boolean | Automatically set |
| count | Integer | Default: 1 |
| collection_id | UUID | Automatically set for recurring bookings. |
| status | String | Default: null. See statuses. |
| person_attributes | Object | See person. Only for input. |
| person | Object | See person. Only for output. |
| resource | Object | See resource. Only for output. |
| service | Object | See service. Only for output. |
| event | Object | See event. Only for output. |
| booking_type | String | Values: appointment or attendance. See service. |
| coupon_id | Integer | Not required |
- awaiting_verification
- verification_expired
- awaiting_payment
- awaiting_confirmation
- confirmed
- declined
- cancelled
- deleted
- checked_in
- in_progress
- completed
- no_show
The normal booking flow when a customer initiates a new booking starts with awaiting_verification. If verification is required Makeplans sends out email or SMS for the customer to verify. When successfully verified the state is updated to confirmed or awaiting_confirmation if reservations requires confirmation by administrator. For confirmation it is then updated to confirmed as normally if confirmed, and to declined if it is not confirmed.
Bookings that have been confirmed and then cancelled, either by customer or administrator, are set to cancelled.
Bookings that are deleted are set to deleted.
Bookings with states awaiting_verification, awaiting_payment, awaiting_confirmation or confirmed are considered to be active. Bookings with state awaiting_verification will be updated with state verification_expired after the current time passes expires_at. However updating states rely on automatic tasks so you must use the active attribute to check whether a booking is active or not. Only active bookings will be returned unless you specify: a booking by id, a specific state such as bookings that are awaiting confirmation, to return all bookings for a resource or dates, or for a person.
See query parameters for filtering the output beyond the default outputs.
GET /bookings will return all active bookings.
GET /bookings/recent will return all active bookings ordered based on updated_at.
GET /bookings/upcoming will return all future active bookings.
GET /bookings/unconfirmed will return only unconfirmed bookings.
GET /bookings/all will return all bookings of all states (including declined, cancelled, deleted, and verification_expired). This is a useful output for synchronisation when you need to keep a track of deleted bookings.
GET /bookings/visible will return all active bookings as well as those declined or cancelled. This is the preferred output if you want to provide a list of all bookings for visual presentation.
GET /bookings/no_status will return all active bookings with no status set.
Response
[
{
"booking": {
"booked_from": "2012-09-29T07:00:00+02:00",
"booked_to": "2012-09-29T08:00:00+02:00",
"created_at": "2012-09-20T15:34:16+02:00",
"custom_data": null,
"count": 1,
"expires_at": null,
"external_id": null,
"id": 1,
"notes": "Very handsome customer",
"person_id": 1,
"resource_id": 1,
"service_id": 1,
"state": "confirmed",
"status": null,
"updated_at": "2012-09-20T15:34:16+02:00"
}
}
]| Name | Type | Description |
|---|---|---|
| service_id | Integer or array of integers | |
| event_id | Integer or array of integers | |
| resource_id | Integer or array of integers | |
| person_id | Integer or array of integers | |
| external_id | String | |
| start | Datetime | booked_from after param |
| end | Datetime | booked_to before param |
| since | Datetime | updated_at after param |
| collection_id | UUID | |
| state | String or array of strings | See states |
| status | String or array of strings | See statuses |
You can return bookings of multiple resources/services/events/people with an array.
| Name | Type | Description |
|---|---|---|
| extended | Boolean | Extend output with full data from related objects. |
GET /bookings/{booking_id} will get booking with id {booking_id}.
You can also find a booking with external_id:
GET /bookings/find_by/external_id/{external_id} will get booking with external_id {external_id}.
POST /bookings will create a new booking.
Bookings without person_id are shown as busy in the calendar.
These parameters are part of booking: booking[public_booking].
| Name | Type | Description |
|---|---|---|
| public_booking | Boolean | Restrict to normal public booking rules such as within opening hours, not able to book in the past or past specified allowed date in the future. Recommended for all customer facing booking applications (e.g. integration on website). Not recommended when synchronising with other calendar programs. Default: false. |
These parameters are not part of booking[]: confirm.
Outgoing messages requires person_id and service_id.
Default action for outgoing messages is according to the settings for booking verification. If email verification is enabled then all *_email messages will be triggered by default to the customer. To override please see parameters for each action below. For admin notification messages the default is based on the account settings. SMS reminders is based on account settings and uses a default value for the time unless specified.
| Name | Type | Description |
|---|---|---|
| confirm | Boolean | If set to false then the 'initiate verification' event is executed. If verification is required the state will be set to `awaiting_verification`. If no verification is required then the state will be set to `awaiting_confirmation` or `confirmed`. |
| ignore_capacity | Boolean | Will force save the booking even though other bookings exists within the same time on the specified resource_id (double booking). Not applicable when `public_booking` is set to true (no double bookings allowed). Default: false. |
| add_reminder_sms | Boolean | Automatically adds `reminder_at` based on setting from account attribute `sms_reminder_time`. Default: at 12PM the day before the appointment. |
| add_messages | Boolean | Automatically generate messages based on message templates. (NOTE: Beta functionality available by invitation.) |
| verification_send_email | Boolean | Send out verification email. Only applicable when `confirm` is set to false. |
| verification_send_sms | Boolean | Send out verification SMS. Only applicable when `confirm` is set to false. |
| confirmation_send_email | Boolean | Send out confirmation email. |
| confirmation_send_sms | Boolean | Send out confirmation SMS. |
| notification_send_email | Boolean | Send out notification email to admin. |
| notification_send_sms | Boolean | Send out notification SMS to admin. |
| extended | Boolean | Extend output with full data from related objects. |
To add a new person along with a booking you must populate person_attributes with person attributes. Values will be matched to an existing person based on national id number, phone number or email (in that order).
POST /bookings/recurring will create recurring bookings based on a pattern.
The recurrence format follows the iCalendar specification{:target="_blank"}. The attributes for recurrence are: RRULE, RDATE, EXDATE. For an introduction and examples of these parameters see this section from the iCalendar specification{:target="_blank"}.
In the iCalendar specification the recurrence is based on values in DTSTART and DTEND. This is set by booked_from and booked_to from booking.
All recurring bookings will except for booked_from and booked_to have the same attributes based on the specified parameters in booking.
All bookings created by the recurring pattern gets the same UUID in collection_id. As the collection name implies, and as is possible with the iCalendar specification, this is not necessarily only for recurrence (i.e. 9am-10am each Friday until December 1st) but also for multiple specific times (as can be specified with RDATE).
Only the collection_id is returned. No bookings are created at the time of request as they will be processed by the server in the background due to the volume of bookings that it is possible to create at one time. A successful response with a collection_id does in no way indicate that any bookings will be created. The first booking as defined in booking is however validated. If it is not valid errors details are returned in the same way as creating a single booking. In such a case recurring rules are not applied and you must adjust the request until validation is successful.
The parameters for recurrence are not set in booking but in recurring.
| Name | Type | Description |
|---|---|---|
| rrule | String | Repeating pattern. Example: `FREQ=DAILY;UNTIL=19971224T000000Z`. |
| rdate | String | List of recurring dates. Example: `VALUE=DATE:19970101,19970120,19970217,19970421`. |
| exdate | String | List of dates that should be excluded from the recurring rule. Example: `VALUE=DATE:19970102`. |
You should always specify COUNT or UNTIL with RRULE. The max number of occurrences is 731, regardless if a limit is set or not.
GET /bookings/recurring/{collection_id} will return all occurrences for a collection.
PUT /bookings/recurring/{collection_id}/cancel will cancel all occurrences for a collection.
DELETE /bookings/recurring/{collection_id} will delete all occurrences for a collection.
PUT /bookings/{booking_id}/verify will verify a booking. The verification code is not checked. Use this when you handle verification in your application.
PUT /bookings/{booking_id}/verify_code will verify a booking using {verification_code}. Use this when Makeplans is used to send out verification email or SMS.
See information about additional parameters.
| Name | Type | Description |
|---|---|---|
| confirmation_send_email | Boolean | Send out confirmation email. |
| confirmation_send_sms | Boolean | Send out confirmation SMS. |
| notification_send_email | Boolean | Send out notification email to admin. Default: based on account setting. |
| notification_send_sms | Boolean | Send out notification SMS to admin. |
| verification_code | String | Verification code send using SMS or email. Only applicable for the `verify_code` action. |
PUT /bookings/{booking_id}/confirm will confirm a booking.
See information about additional parameters.
| Name | Type | Description |
|---|---|---|
| confirmation_send_email | Boolean | Send out confirmation email. |
| confirmation_send_sms | Boolean | Send out confirmation SMS. |
| notification_send_email | Boolean | Send out notification email to admin. |
| notification_send_sms | Boolean | Send out notification SMS to admin. |
PUT /bookings/{booking_id}/decline will decline a booking.
See information about additional parameters.
| Name | Type | Description |
|---|---|---|
| decline_send_email | Boolean | Send out decline email. |
| decline_send_sms | Boolean | Send out decline SMS. |
PUT /bookings/{booking_id}/cancel will cancel a booking.
See information about additional parameters.
| Name | Type | Description |
|---|---|---|
| cancellation_send_email | Boolean | Send out cancellation email. |
| cancellation_send_sms | Boolean | Send out cancellation SMS. |
PUT /bookings/{booking_id} will update a booking.
See information about additional parameters.
| Name | Type | Description |
|---|---|---|
| ignore_capacity | Boolean | Set to true to allow a double booking. |
| add_reminder_sms | Boolean | Automatically adds `reminder_at`. |
| modification_send_email | Boolean | Send out modification email. |
| modification_send_sms | Boolean | Send out modification SMS. |
| extended | Boolean | Extend output with full data from related objects. |
DELETE /bookings/{booking_id} will delete existing booking with id {booking_id}.
Deleting a booking will set it to state=deleted and active=false. It will not be visible in listing, only when requesting GET /bookings/all or by requesting the booking directly GET /bookings/{booking_id}.
Do not use this method if the booking is rescheduled or cancelled.
See information about additional parameters.
| Name | Type | Description |
|---|---|---|
| cancellation_send_email | Boolean | Send out cancellation email. |
| cancellation_send_sms | Boolean | Send out cancellation SMS. |
PUT /bookings/{booking_id}/status will update the booking status.
| Name | Type | Description |
|---|---|---|
| status | String | Booking status. |
This parameter is specified in the same way as additional parameters.