# Bookers Bookers are a Person that created a Booking using Bookinglayer. Each Booker contains Person data with an addition of some booking related data. The data contained within the Booker is a snapshot of the Person at the time of making the Booking. This means the Person resource could potentially have fresher data than that of any of the Booker resources tied to the Person. Anyway, the Person always contains the freshest data and Bookers contain their snapshots. ## The Booker object ```json { "person": { "id": "6e3ab460-55cf-11e7-9300-04016aacf401", "first_name": "John", "last_name": "Smith", "initials": "JS", "gender": "male", "birth_date": "2003-08-20", "email": "john.smith@bookinglayer.com", "language_code": "en", "nationality_code": "gb", "phone_country_calling_code": "44", "phone_country_code": "gb", "phone": "2071234567", "country_code": "gb", "state": "England", "city": "London", "zip_code": "SW1A 1AA", "address_line_1": "10 Downing Street", "address_line_2": null, "address_line_3": null, "custom_fields": { "surf_level_6375066bbc27f": "550e8400-e29b-41d4-a716-446655440000", "yoga_level_61f2619ca4746": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "dietary_requirements_61f2619ca4746": "vegan" }, "totals": { "last_booking": "2020-04-15T13:08:58+00:00", "booking_count": 2, "total_as_guest": 2, "total_as_booker": 1, "total_paid_as_booker": 2310, "booking_inquiry_count": 1 }, "id_type": "passport", "id_number": "7700225VH", "id_expiry_date": "2030-01-10", "company_name": "Bookinglayer", "tax_number": "AB123456D", "diet_id": 357, "diet": { "id": 357, "backoffice_title": "Omnivorous", "abbreviation": "OV" }, "is_guest": false, "is_booker": true, "created_at": "2017-06-20T15:45:05+00:00", "updated_at": "2020-04-15T13:08:58+00:00" }, "booking_related_data": { "booking_id": "83d8ac7b-10c5-3839-abfc-9c2d9643cac5", } } ``` The `Person` resource is already explained in [its own page](/api/core-resources/persons.md#the-person-object), and the only additional data this resource offers is the `booking_related_data.booking_id`. #### `booking_related_data.booking_id` ID of the Booking the Booker is assigned to. ## Endpoints Bookers are closely entangled with Bookings and cannot exist without them, nor can Bookings exist without Bookers. Due to that tight coupling it is not possible to create nor delete Bookers on their own. Instead, bookers are always created/deleted along with their Bookings. ## Fetch a Booking Booker `GET` `https://api.bookinglayer.io/private/bookings/{booking_id}/booker` Fetches a Booker for the specified Booking. #### Path Parameters | Name | Type | Description | | ----------- | ---- | ------------------------------------------------ | | booking\_id | UUID | ID of the booking the fetched Booker belongs to. | {% tabs %} {% tab title="200: OK " %} ```json { "data": { "id": "b36911bf-d996-4192-a1ef-86863d5284d3", "person": { "id": "6e3ab460-55cf-11e7-9300-04016aacf401", "first_name": "John", "last_name": "Smith", "initials": "JS", "gender": "male", "birth_date": "2003-08-20", "email": "john.smith@bookinglayer.com", "language_code": "en", "nationality_code": "gb", "phone_country_calling_code": "44", "phone_country_code": "gb", "phone": "2071234567", "country_code": "gb", "state": "England", "city": "London", "zip_code": "SW1A 1AA", "address_line_1": "10 Downing Street", "address_line_2": null, "address_line_3": null, "custom_fields": { "surf_level_6375066bbc27f": "550e8400-e29b-41d4-a716-446655440000", "yoga_level_61f2619ca4746": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "dietary_requirements_61f2619ca4746": "vegan" }, "totals": { "last_booking": "2020-04-15T13:08:58+00:00", "booking_count": 2, "total_as_guest": 2, "total_as_booker": 1, "total_paid_as_booker": 2310, "booking_inquiry_count": 1 }, "id_type": "passport", "id_number": "7700225VH", "id_expiry_date": "2030-01-10", "company_name": "Bookinglayer", "tax_number": "AB123456D", "diet_id": 357, "diet": { "id": 357, "backoffice_title": "Omnivorous", "abbreviation": "OV" }, "is_guest": false, "is_booker": true, "created_at": "2017-06-20T15:45:05+00:00", "updated_at": "2020-04-15T13:08:58+00:00" }, "booking_related_data": { "booking_id": "83d8ac7b-10c5-3839-abfc-9c2d9643cac5", "company_name": "Bookinglayer", "tax_number": "1234567WA" } } } ``` {% endtab %} {% endtabs %} ## Update a Booking Booker `PUT` `https:/api.bookinglayer.io/private/bookings/{booking_id}/booker` Updates a Booker entity. Updating a Booker will also update its Person entity, because Persons always contain the latest data from their Booker/Guest instances. When updating a Booker's email there are three possible flows based on the `create_new` flag and whether the new email you are setting is already assigned to another Person. The first flow, when the `create_new` flag is missing or `null` and a new email is provided, will update the email of the Booker, as well as the Person. The second flow is initiated by sending the `create_new` flag as `true` and, again, sending an email that is not assigned to any other Person. In this case a new Person will be created, the Booker being updated attached to it and detached from its old Person. The last flow is relevant when an email that is already assigned to another person is sent. In this flow the `create_new` flag has no effect, and the Booker is merged with the existing Person. #### Path Parameters | Name | Type | Description | | --------------------------------------------- | ---- | --------------------------------------- | | booking\_id\* | UUID | ID of the booking the guest belongs to. | | guest\_id\* | UUID | ID of the guest that should be updated. | #### Request Body | Name | Type | Description | | -------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------- | | email | email | Update the Bookers email or creates a new Person, depending on the `create_new` flag. | | salutation | string | Updates the Bookers salutation. | | first\_name | string | Updates the Bookers first name. | | last\_name | String | Updates the Bookers last name. | | language\_code | Country alpha-2 code. | Updates the Bookers language. | | phone\_country\_code | Country alpha-2 code. | Updates the Bookers phone country code and phone calling code accordingly. | | phone | string | Updates the Bookers phone. | | address\_line\_1 | string | Updates the Bookers address line 1. | | address\_line\_2 | string | Updates the Bookers address line 2. | | address\_line\_3 | string | Updates the Bookers address line 3. | | zip\_code | string | Updates the Bookers zip code. | | city | string | Updates the Bookers city. | | state | string | Updates the Bookers state. | | tax\_number | string | Updates the Bookers tax number. | | birth\_date | date | Updates the Bookers birth date. | | gender | male or female | Updates the Bookers gender. | | country\_code | Country alpha-2 code. | Updates the Bookers country. | | nationality\_code | Country alpha-2 code. | Updates the Guest nationality. | | id\_type | id\_card, passport, driver\_license or other | Updates the Bookers ID type. | | id\_number | string | Updates the Bookers ID number. | | id\_expiry\_date | date | Updates the Bookers ID expiration date. | | custom\_fields | object | Updates the Bookers custom fields. | | create\_new | bool | Determines whether to create a new Person or not. Only takes effect when `email` is updated. | {% tabs %} {% tab title="200: OK " %} ```json { "data": { "id": "b36911bf-d996-4192-a1ef-86863d5284d3", "person": { "id": "6e3ab460-55cf-11e7-9300-04016aacf401", "first_name": "John", "last_name": "Smith", "initials": "JS", "gender": "male", "birth_date": "2003-08-20", "email": "john.smith@bookinglayer.com", "language_code": "en", "nationality_code": "gb", "phone_country_calling_code": "44", "phone_country_code": "gb", "phone": "2071234567", "country_code": "gb", "state": "England", "city": "London", "zip_code": "SW1A 1AA", "address_line_1": "10 Downing Street", "address_line_2": null, "address_line_3": null, "custom_fields": { "surf_level_6375066bbc27f": "550e8400-e29b-41d4-a716-446655440000", "yoga_level_61f2619ca4746": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "dietary_requirements_61f2619ca4746": "vegan" }, "totals": { "last_booking": "2020-04-15T13:08:58+00:00", "booking_count": 2, "total_as_guest": 2, "total_as_booker": 1, "total_paid_as_booker": 2310, "booking_inquiry_count": 1 }, "id_type": "passport", "id_number": "7700225VH", "id_expiry_date": "2030-01-10", "company_name": "Bookinglayer", "tax_number": "AB123456D", "diet_id": 357, "diet": { "id": 357, "backoffice_title": "Omnivorous", "abbreviation": "OV" }, "is_guest": false, "is_booker": true, "created_at": "2017-06-20T15:45:05+00:00", "updated_at": "2020-04-15T13:08:58+00:00" }, "booking_related_data": { "booking_id": "83d8ac7b-10c5-3839-abfc-9c2d9643cac5", "company_name": "Bookinglayer", "tax_number": "1234567WA" } } } ``` {% endtab %} {% endtabs %} ## Webhooks Webhooks are a mechanism for Bookinglayer to notify other apps when something happens in the system. They are described in detail in a dedicated [Webhooks document](/api/webhooks.md). ### `BookerCreated` Sends a new Booker ID via a webhook call when a Booker gets created. Bookers are created when Bookings are created so a `BookingCreated` webhook call could be triggered by the same action that triggers `BookerCreated`. Also, if this is the Bookers first appearance in Bookinglayer a Person for that booker will be created and the `PersonCreated` webhook call could be dispatched as well. ```json { "event": "BookerCreated", "data": { "person_id": "370f14de-ea41-4b0a-8e55-ab2875457dee", "booking_id": "70a50883-4c15-4831-b041-06c5fb551d28" } } ``` ### `BookerUpdated` Sends a Booker ID via a webhook call when an existing Booker gets updated. Updating Booker data also updates the Person this booker belongs to so the `PersonUpdated` webhook call could be triggered by the same action. ```json { "event": "BookerUpdated", "data": { "person_id": "f2567477-dc1a-416a-8acd-aeec6a34d99b", "booking_id": "804d5cd9-e950-42df-b89f-79872849faa3", } } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bookinglayer.com/api/core-resources/bookers.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.