Bookers

Bookers are also an extension of the Person resource, except Bookers are the ones who create bookings in the system whereas Guests are actually participating in the Booking.

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

{
    "person": {
        "id": "6e3ab460-55cf-11e7-9300-04016aacf401",
        "first_name": "John",
        "last_name": "Smith",
        "initials": "JS",
        "gender": "male",
        "birth_date": "2003-08-20",
        "email": "[email protected]",
        "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, 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.

200: OK

{
    "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": "[email protected]",
            "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"
        }
    }
}

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.

200: OK

{
    "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": "[email protected]",
            "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"
        }
    }
}

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.

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.

{
    "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.

{
    "event": "BookerUpdated",
    "data": {
        "person_id": "f2567477-dc1a-416a-8acd-aeec6a34d99b",
        "booking_id": "804d5cd9-e950-42df-b89f-79872849faa3",
    }
}