| 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 |
## States
* awaiting_verification
* verification_expired
* awaiting_payment
* awaiting_confirmation
* confirmed
* declined
* cancelled
* deleted
## Statuses
* checked_in
* in_progress
* completed
* no_show
### Normal state flow
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`.
## Active bookings
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.
## Listing
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
```json
[
{
"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"
}
}
]
```
### Query Parameters
| 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. |
### Add new booking with new person
To add a new person along with a booking you must populate `person_attributes` with [person](/endpoints/people/) attributes. Values will be matched to an existing person based on national id number, phone number or email (in that order).
## Add recurring bookings
`POST /bookings/recurring` will create recurring bookings based on a pattern.
The recurrence format follows the [iCalendar specification](https://tools.ietf.org/html/rfc5545){: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](http://www.kanzaki.com/docs/ical/rrule.html){: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.
### Parameters for recurrence
The parameters for recurrence are not set in `booking` but in `recurring`.