Guests

Guests are an extension of the `Person` and represent their relationships with `Booking` instances.

Guests are basically Persons in relation with Bookings. Each Guest contains the same person data and additional booking related data. It is important to note that the data contained within a Guest does not necessarily have to match the data contained within the Person related to this guest. This is caused by the fact that each time a Guest is added to a Booking they enter all the required information again. For that reason, each Guest could have data different than the Person it belongs to, and the person will always hold the data from the latest Booking.

The Guest 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": true,
        "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",
        "web_checked_in_at": "2023-05-01",
        "check_in_at": "2023-05-05",
        "checked_in_at": "2023-05-05T08:33:54+00:00",
        "check_out_at": "2023-05-25",
        "checked_out_at": null,
        "arrival_date": "2023-05-05",
        "odd_arrival_date": null,
        "arrival_time": "08:35:00",
        "arrival_location_id": 52632,
        "arrival_location": {
            "id": 52632,
            "title": "Hotel A",
            "abbreviation": "HTLA"
        },
        "arrival_flight": "W221HFS",
        "arrival_airline": "Wintheiser PLC",
        "departure_date": "2023-05-26",
        "odd_departure_date": "2023-05-26",
        "departure_time": "18:30:00",
        "departure_location": {
            "id": 52633,
            "title": "Hotel B",
            "abbreviation": "HTLB"
        },
        "departure_flight": "ZGK3RR1",
        "departure_airline": "Ziegler Group",
        "transfer_comment": null,
        "final_price_incl_tax": 500,
        "cancelled_at": null,
        "created_at": "2023-12-01T15:29:13+00:00",
        "updated_at": "2023-12-01T15:29:13+00:00"
    }
}

Since the Person resource is already explained in its own page, this document will focus on booking_related_data.

booking_related_data.booking_id

ID of the booking the Guest is assigned to.

booking_related_data.web_checked_in_at [nullable]

The date and time the guest completed their online check-in.

booking_related_data.check_in_at [nullable]

The date the guest is supposed to check in on.

booking_related_data.checked_in_at [nullable]

The date and time the guest actually checks in.

booking_related_data.check_out_at [nullable]

The date the guest is supposed to check out on.

booking_related_data.checked_out_at [nullable]

The date and time the guest actually checks out.

booking_related_data.arrival_date [nullable]

The date the guest is supposed to arrive on.

booking_related_data.odd_arrival_date [nullable]

In case the actual date of guests arrival is different from the start_date of the guests earliest booking line this field is used for specifying the actual arrival date.

booking_related_data.arrival_time [nullable]

The time the guest is due to arrive at.

booking_related_data.arrival_location_id [nullable]

ID of the location the guest will arrive to.

booking_related_data.arrival_location.id

Expanded ID of the location the guest will arrive to.

booking_related_data.arrival_location.backoffice_title

Expanded title of the location the guest will arrive to.

booking_related_data.arrival_location.abbreviation

Expanded abbreviation of the title of the location the guest will arrive to.

booking_related_data.arrival_flight [nullable]

Number of the flight the guest will arrive on.

booking_related_data.arrival_airline [nullable]

Name of the airline operating the guests arrival flight.

booking_related_data.departure_date [nullable]

The date the guest is supposed to leave.

booking_related_data.odd_departure_date [nullable]

In case the actual date of guests departure is different from the end_date of the guests latest booking line this field is used for specifying the actual departure date.

booking_related_data.departure_time [nullable]

The time the guest is due to depart at.

booking_related_data.departure_location_id [nullable]

ID of the location the guest will depart from.

booking_related_data.departure_location.id

Expanded ID of the location the guest will depart from.

booking_related_data.departure_location.backoffice_title

Expanded title of the location the guest will depart from.

booking_related_data.departure_location.abbreviation

Expanded abbreviation of the title of the location the guest will depart from.

booking_related_data.departure_flight [nullable]

Number of the flight the guest will depart on.

booking_related_data.departure_airline [nullable]

Name of the airline operating the guests departure flight.

booking_related_data.transfer_comment [nullable]

Arbitrary comments about the Guest's transfer.

booking_related_data.final_price_incl_tax

The total cost of the booking for the relevant guest.

booking_related_data.cancelled_at [nullable]

The date and time when this guest was cancelled. Contains null if the guest is not cancelled.

booking_related_data.created_at

The date and time when this guest was created. Note: this is the date and time of creating the relationship between the booking and the person, not the date and time when the person was created.

booking_related_data.updated_at

The date and time when the guest was last modified. Note: this represents the last time the guest was modified, not the person.

Endpoints

List guests

get

List all guests

Query parameters
limitinteger · int32 · min: 1 · max: 100Optional

Number of guests to return

Default: 10
pageinteger · int32 · min: 1Optional

Page number

Default: 1
sort_byobject · enumOptional

Sorts the results based on the passed field. All possible values can be appended with ",asc" or ",desc"

Possible values:
arrives_atstring · datetime or rangeOptional

Filter by arrival date

Example: 2024-05-10,2024-05-15
arrival_location_idstring · Single ID or listOptional

Filter by arrival location

Example: 55,24
departs_atstring · datetime or rangeOptional

Filter by departure date

Example: 2024-05-10,2024-05-15
departure_location_idstring · Single ID or listOptional

Filter by departure location

Example: 55,31
checked_in_atstring · datetime, range, `null` or `notnull`Optional

Filter by check-in date

Example: 2024-05-10 10:30:00,2024-05-10 12:30:00
checked_out_atstring · datetime, range, `null` or `notnull`Optional

Filter by check-out date

Example: 2024-05-10 10:30:00,2024-05-10 12:30:00
booking_statusstring · Booking status or list of booking statusesOptional

Filter by booking status

Example: deposit_paid,paid
check_in_atstring · datetime or rangeOptional

Filter by guest check in date

Example: 2024-05-10,2024-05-15
check_out_atstring · datetime or rangeOptional

Filter by guest check out date

Example: 2024-05-10,2024-05-15
booking_idstring · single ID or listOptional

Filter by booking ID's

Example: b2238384-ff48-46d4-9034-912db04a10c4,48a8b17d-c166-4c95-a12d-1021c29ffb1b
booking_product_idstring · single ID or listOptional

Filter by booking line product ID's

Example: b2238384-ff48-46d4-9034-912db04a10c4,48a8b17d-c166-4c95-a12d-1021c29ffb1b
booking_product_typestring · single type or listOptional

Filter by booking line product types

Example: accommodation,activity
booking_product_variant_idstring · single ID or listOptional

Filter by booking line product variant ID's

Example: b2238384-ff48-46d4-9034-912db04a10c4,48a8b17d-c166-4c95-a12d-1021c29ffb1b
booking_location_idstring · Single ID or listOptional

Filter by booking location ID

Example: 55,24
diet_idstring · Single ID or listOptional

Filter by guest diet ID

Example: 55,24
on_site_atstring · datetime or rangeOptional

Filter guests that are on-site at the provided date(time)

Example: 2024-05-10
Responses
200

A list of guests

application/json
get
/guests
GET /private/guests HTTP/1.1
Host: api.bookinglayer.io
Accept: */*
200

A list of guests

[
  {
    "person": {
      "phone_country_calling_code": "34",
      "gender": "male",
      "city": "city",
      "birth_date": "2000-01-23",
      "created_at": "2000-01-23T04:56:07.000+00:00",
      "nationality_code": "en",
      "zip_code": "zip_code",
      "language_code": "en",
      "updated_at": "2000-01-23T04:56:07.000+00:00",
      "tax_number": "tax_number",
      "address_line_1": "address_line_1",
      "address_line_3": "address_line_3",
      "id_type": "id_type",
      "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
      "state": "state",
      "address_line_2": "address_line_2",
      "first_name": "first_name",
      "email": "email",
      "id_number": "id_number",
      "phone_country_code": "es",
      "initials": "initials",
      "id_expiry_date": "2000-01-23",
      "custom_fields": "{}",
      "last_name": "last_name",
      "totals": "{}",
      "deleted_at": "2000-01-23T04:56:07.000+00:00",
      "country_code": "ES",
      "phone": "phone",
      "company_name": "company_name",
      "company_address_line_1": "company_address_line_1",
      "company_address_line_2": "company_address_line_2"
    },
    "booking_related_data": {
      "departure_airline": "departure_airline",
      "arrival_time": "arrival_time",
      "departure_flight": "departure_flight",
      "odd_arrival_date": "2000-01-23",
      "arrival_flight": "arrival_flight",
      "departure_date": "2000-01-23",
      "departure_location_id": 6,
      "level_id": 5,
      "odd_departure_date": "2000-01-23",
      "guest_group_id": 1,
      "web_check_in_at": "2000-01-23T04:56:07.000+00:00",
      "check_out_at": "2000-01-23T04:56:07.000+00:00",
      "transfer_comment": "transfer_comment",
      "checked_out_at": "2000-01-23T04:56:07.000+00:00",
      "arrival_airline": "arrival_airline",
      "arrival_location_id": 0,
      "checked_in_at": "2000-01-23T04:56:07.000+00:00",
      "check_in_at": "2000-01-23T04:56:07.000+00:00",
      "arrival_date": "2000-01-23",
      "departure_time": "departure_time"
    }
  }
]

Create a guest

post

Create a guest for a booking

Path parameters
booking_idstring · uuidRequired

ID of the booking to create a guest for

Body
Responses
post
/bookings/{booking_id}/guests
POST /private/bookings/{booking_id}/guests HTTP/1.1
Host: api.bookinglayer.io
Content-Type: application/json
Accept: */*
Content-Length: 1602

{
  "person": {
    "phone_country_calling_code": "34",
    "gender": "male",
    "city": "city",
    "birth_date": "2000-01-23",
    "created_at": "2000-01-23T04:56:07.000+00:00",
    "nationality_code": "en",
    "zip_code": "zip_code",
    "language_code": "en",
    "updated_at": "2000-01-23T04:56:07.000+00:00",
    "tax_number": "tax_number",
    "address_line_1": "address_line_1",
    "address_line_3": "address_line_3",
    "id_type": "id_type",
    "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
    "state": "state",
    "address_line_2": "address_line_2",
    "first_name": "first_name",
    "email": "email",
    "id_number": "id_number",
    "phone_country_code": "es",
    "initials": "initials",
    "id_expiry_date": "2000-01-23",
    "custom_fields": "{}",
    "last_name": "last_name",
    "totals": "{}",
    "deleted_at": "2000-01-23T04:56:07.000+00:00",
    "country_code": "ES",
    "phone": "phone",
    "company_name": "company_name",
    "company_address_line_1": "company_address_line_1",
    "company_address_line_2": "company_address_line_2"
  },
  "booking_related_data": {
    "departure_airline": "departure_airline",
    "arrival_time": "arrival_time",
    "departure_flight": "departure_flight",
    "odd_arrival_date": "2000-01-23",
    "arrival_flight": "arrival_flight",
    "departure_date": "2000-01-23",
    "departure_location_id": 6,
    "level_id": 5,
    "odd_departure_date": "2000-01-23",
    "guest_group_id": 1,
    "web_check_in_at": "2000-01-23T04:56:07.000+00:00",
    "check_out_at": "2000-01-23T04:56:07.000+00:00",
    "transfer_comment": "transfer_comment",
    "checked_out_at": "2000-01-23T04:56:07.000+00:00",
    "arrival_airline": "arrival_airline",
    "arrival_location_id": 0,
    "checked_in_at": "2000-01-23T04:56:07.000+00:00",
    "check_in_at": "2000-01-23T04:56:07.000+00:00",
    "arrival_date": "2000-01-23",
    "departure_time": "departure_time"
  }
}
201

The created guest

{
  "person": {
    "phone_country_calling_code": "34",
    "gender": "male",
    "city": "city",
    "birth_date": "2000-01-23",
    "created_at": "2000-01-23T04:56:07.000+00:00",
    "nationality_code": "en",
    "zip_code": "zip_code",
    "language_code": "en",
    "updated_at": "2000-01-23T04:56:07.000+00:00",
    "tax_number": "tax_number",
    "address_line_1": "address_line_1",
    "address_line_3": "address_line_3",
    "id_type": "id_type",
    "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
    "state": "state",
    "address_line_2": "address_line_2",
    "first_name": "first_name",
    "email": "email",
    "id_number": "id_number",
    "phone_country_code": "es",
    "initials": "initials",
    "id_expiry_date": "2000-01-23",
    "custom_fields": "{}",
    "last_name": "last_name",
    "totals": "{}",
    "deleted_at": "2000-01-23T04:56:07.000+00:00",
    "country_code": "ES",
    "phone": "phone",
    "company_name": "company_name",
    "company_address_line_1": "company_address_line_1",
    "company_address_line_2": "company_address_line_2"
  },
  "booking_related_data": {
    "departure_airline": "departure_airline",
    "arrival_time": "arrival_time",
    "departure_flight": "departure_flight",
    "odd_arrival_date": "2000-01-23",
    "arrival_flight": "arrival_flight",
    "departure_date": "2000-01-23",
    "departure_location_id": 6,
    "level_id": 5,
    "odd_departure_date": "2000-01-23",
    "guest_group_id": 1,
    "web_check_in_at": "2000-01-23T04:56:07.000+00:00",
    "check_out_at": "2000-01-23T04:56:07.000+00:00",
    "transfer_comment": "transfer_comment",
    "checked_out_at": "2000-01-23T04:56:07.000+00:00",
    "arrival_airline": "arrival_airline",
    "arrival_location_id": 0,
    "checked_in_at": "2000-01-23T04:56:07.000+00:00",
    "check_in_at": "2000-01-23T04:56:07.000+00:00",
    "arrival_date": "2000-01-23",
    "departure_time": "departure_time"
  }
}

Update a guest

put

Update a guest by ID

Path parameters
booking_idstring · uuidRequired

ID of the booking to update a guest for

guest_idstring · uuidRequired

ID of the guest to update

Body
Responses
200

The updated guest

application/json
put
/bookings/{booking_id}/guests/{guest_id}
PUT /private/bookings/{booking_id}/guests/{guest_id} HTTP/1.1
Host: api.bookinglayer.io
Content-Type: application/json
Accept: */*
Content-Length: 1602

{
  "person": {
    "phone_country_calling_code": "34",
    "gender": "male",
    "city": "city",
    "birth_date": "2000-01-23",
    "created_at": "2000-01-23T04:56:07.000+00:00",
    "nationality_code": "en",
    "zip_code": "zip_code",
    "language_code": "en",
    "updated_at": "2000-01-23T04:56:07.000+00:00",
    "tax_number": "tax_number",
    "address_line_1": "address_line_1",
    "address_line_3": "address_line_3",
    "id_type": "id_type",
    "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
    "state": "state",
    "address_line_2": "address_line_2",
    "first_name": "first_name",
    "email": "email",
    "id_number": "id_number",
    "phone_country_code": "es",
    "initials": "initials",
    "id_expiry_date": "2000-01-23",
    "custom_fields": "{}",
    "last_name": "last_name",
    "totals": "{}",
    "deleted_at": "2000-01-23T04:56:07.000+00:00",
    "country_code": "ES",
    "phone": "phone",
    "company_name": "company_name",
    "company_address_line_1": "company_address_line_1",
    "company_address_line_2": "company_address_line_2"
  },
  "booking_related_data": {
    "departure_airline": "departure_airline",
    "arrival_time": "arrival_time",
    "departure_flight": "departure_flight",
    "odd_arrival_date": "2000-01-23",
    "arrival_flight": "arrival_flight",
    "departure_date": "2000-01-23",
    "departure_location_id": 6,
    "level_id": 5,
    "odd_departure_date": "2000-01-23",
    "guest_group_id": 1,
    "web_check_in_at": "2000-01-23T04:56:07.000+00:00",
    "check_out_at": "2000-01-23T04:56:07.000+00:00",
    "transfer_comment": "transfer_comment",
    "checked_out_at": "2000-01-23T04:56:07.000+00:00",
    "arrival_airline": "arrival_airline",
    "arrival_location_id": 0,
    "checked_in_at": "2000-01-23T04:56:07.000+00:00",
    "check_in_at": "2000-01-23T04:56:07.000+00:00",
    "arrival_date": "2000-01-23",
    "departure_time": "departure_time"
  }
}
200

The updated guest

{
  "person": {
    "phone_country_calling_code": "34",
    "gender": "male",
    "city": "city",
    "birth_date": "2000-01-23",
    "created_at": "2000-01-23T04:56:07.000+00:00",
    "nationality_code": "en",
    "zip_code": "zip_code",
    "language_code": "en",
    "updated_at": "2000-01-23T04:56:07.000+00:00",
    "tax_number": "tax_number",
    "address_line_1": "address_line_1",
    "address_line_3": "address_line_3",
    "id_type": "id_type",
    "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
    "state": "state",
    "address_line_2": "address_line_2",
    "first_name": "first_name",
    "email": "email",
    "id_number": "id_number",
    "phone_country_code": "es",
    "initials": "initials",
    "id_expiry_date": "2000-01-23",
    "custom_fields": "{}",
    "last_name": "last_name",
    "totals": "{}",
    "deleted_at": "2000-01-23T04:56:07.000+00:00",
    "country_code": "ES",
    "phone": "phone",
    "company_name": "company_name",
    "company_address_line_1": "company_address_line_1",
    "company_address_line_2": "company_address_line_2"
  },
  "booking_related_data": {
    "departure_airline": "departure_airline",
    "arrival_time": "arrival_time",
    "departure_flight": "departure_flight",
    "odd_arrival_date": "2000-01-23",
    "arrival_flight": "arrival_flight",
    "departure_date": "2000-01-23",
    "departure_location_id": 6,
    "level_id": 5,
    "odd_departure_date": "2000-01-23",
    "guest_group_id": 1,
    "web_check_in_at": "2000-01-23T04:56:07.000+00:00",
    "check_out_at": "2000-01-23T04:56:07.000+00:00",
    "transfer_comment": "transfer_comment",
    "checked_out_at": "2000-01-23T04:56:07.000+00:00",
    "arrival_airline": "arrival_airline",
    "arrival_location_id": 0,
    "checked_in_at": "2000-01-23T04:56:07.000+00:00",
    "check_in_at": "2000-01-23T04:56:07.000+00:00",
    "arrival_date": "2000-01-23",
    "departure_time": "departure_time"
  }
}

Delete a guest

delete

Delete a guest by ID

Path parameters
booking_idstring · uuidRequired

ID of the booking to delete a guest for

guest_idstring · uuidRequired

ID of the guest to delete

Responses
delete
/bookings/{booking_id}/guests/{guest_id}
DELETE /private/bookings/{booking_id}/guests/{guest_id} HTTP/1.1
Host: api.bookinglayer.io
Accept: */*

No content

Get a guest

get

Get a guest by ID

Path parameters
booking_idstring · uuidRequired

ID of the booking to get a guest for

guest_idstring · uuidRequired

ID of the guest to get

Query parameters
Responses
200

A guest

application/json
get
/bookings/{booking_id}/guests/{guest_id}
GET /private/bookings/{booking_id}/guests/{guest_id} HTTP/1.1
Host: api.bookinglayer.io
Accept: */*
200

A guest

{
  "person": {
    "phone_country_calling_code": "34",
    "gender": "male",
    "city": "city",
    "birth_date": "2000-01-23",
    "created_at": "2000-01-23T04:56:07.000+00:00",
    "nationality_code": "en",
    "zip_code": "zip_code",
    "language_code": "en",
    "updated_at": "2000-01-23T04:56:07.000+00:00",
    "tax_number": "tax_number",
    "address_line_1": "address_line_1",
    "address_line_3": "address_line_3",
    "id_type": "id_type",
    "id": "046b6c7f-0b8a-43b9-b35d-6489e6daee91",
    "state": "state",
    "address_line_2": "address_line_2",
    "first_name": "first_name",
    "email": "email",
    "id_number": "id_number",
    "phone_country_code": "es",
    "initials": "initials",
    "id_expiry_date": "2000-01-23",
    "custom_fields": "{}",
    "last_name": "last_name",
    "totals": "{}",
    "deleted_at": "2000-01-23T04:56:07.000+00:00",
    "country_code": "ES",
    "phone": "phone",
    "company_name": "company_name",
    "company_address_line_1": "company_address_line_1",
    "company_address_line_2": "company_address_line_2"
  },
  "booking_related_data": {
    "departure_airline": "departure_airline",
    "arrival_time": "arrival_time",
    "departure_flight": "departure_flight",
    "odd_arrival_date": "2000-01-23",
    "arrival_flight": "arrival_flight",
    "departure_date": "2000-01-23",
    "departure_location_id": 6,
    "level_id": 5,
    "odd_departure_date": "2000-01-23",
    "guest_group_id": 1,
    "web_check_in_at": "2000-01-23T04:56:07.000+00:00",
    "check_out_at": "2000-01-23T04:56:07.000+00:00",
    "transfer_comment": "transfer_comment",
    "checked_out_at": "2000-01-23T04:56:07.000+00:00",
    "arrival_airline": "arrival_airline",
    "arrival_location_id": 0,
    "checked_in_at": "2000-01-23T04:56:07.000+00:00",
    "check_in_at": "2000-01-23T04:56:07.000+00:00",
    "arrival_date": "2000-01-23",
    "departure_time": "departure_time"
  }
}

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.

GuestCreated

Sends a new Guest ID via a webhook call when a Guest gets created. If this is the first time that Person is being created in Bookinglayer the PersonCreated event would get dispatched at the same time as well, so you should be careful if you're subscribed to both events.

{
    "event": "GuestCreated",
    "data": {
        "person_id": "0bfacfba-9a71-414a-8736-4c16bba211b5",
        "booking_id": "a4a853cc-9769-4e88-9640-469507b2ccaa"
    }
}

GuestUpdated

Sends a Guest ID via a webhook call when an existing Guest gets updated. Updating a Guest also results in updating the Person that Guest belongs to so the PersonUpdated event would get dispatched at the same time. 

{
    "event": "GuestUpdated",
    "data": {
        "person_id": "1d08ccbe-f978-42ed-be95-1c5a09ba1ca2",
        "booking_id": "eac4506b-0dbd-4576-b7a1-c49612ec801b"
    }
}

GuestDeleted

Sends a Person ID and Booking ID via a webhook call when an existing Guest gets deleted. Deleting a Guest from a Booking does not automatically delete the Person the guest belonged to so there are no conflicts in this scenario.

{
    "event": "GuestDeleted",
    "data": {
        "person_id": "9e9f1565-d87f-4222-bff3-abd9faa37e75",
        "booking_id": "3b3b4f72-3cb7-444d-bc7a-d60873a09efb"
    }
}
PreviousPersonsNextBookers

Last updated