Persons
All your dear guests and bookers in one place.
The Person
object represents the Guest
or the Booker
or both at the same time. A Guest
in our system means a Person
who uses the purchased services or accommodations. while a booker
is a person who placed and manages the Booking
Of significance is that the Person
object retains the latest status from their preceding booking. To illustrate, if an individual, using the email address john@bookinglayer.com, places a Booking
on a Monday with the phone number +1 321 123 321
, and subsequently makes another Booking
on a Wednesday with the number +34 555 555 555
, the latter number (+34 555 555 555) will be displayed within the individual's Person
profile.
However, this does not mean that the previous number will be lost - it will be visible in the relationship between the Booking
and the Person
, represented by the Guest
resource.
The Person object
id
Unique ID of the person.
first_name
The person's first name.
last_name
The person's last name.
initials
The person's initials.
gender
The Person's gender. Nullable Enum (male
, female
). The field is mainly used to filter gender-oriented rooms. If you want to ask for gender and provide more options we recommend using Custom Fields
birth_date
The Person's birth date in format yyyy-mm-dd
.
email
The Person's email must be unique.
language_code
Country ISO 3166-1 alpha-2 codes representing the Person's selected language.
nationality_code
Country ISO 3166-1 alpha-2 codes representing the Person's selected nationality.
phone_country_calling_code
2 or 3 digit country calling code in example for Great Britain 44.
phone_country_code
Country ISO 3166-1 alpha-2 codes representing the Person's phone country code.
phone
Phone number without calling code, whitespaces.
country_code
Country ISO 3166-1 alpha-2 codes representing the Person's country.
state
State, province, or region.
city
City, district, suburb, town, or village.
zip_code
ZIP or postal code.
address_line_1
Address line 1 (e.g. street, PO Box or company name).
address_line_2
Address line 2 (e.g. apartment, suite, unit or building).
address_line_3
Address line 3 (e.g. room number).
custom_fields
An object in which the keys represent custom field ID's, while the values store the corresponding values.
totals
An object in which the keys represent total type, while the values store the corresponding values.
totals.last_booking
The date of the most recent Booking
where the Person
acted as either a guest or booker.
totals.booking_count
The count of Bookings
where the Person
acted as either a guest or booker.
totals.total_as_guest
The count of Bookings
where the Person
acted as guest.
totals.total_as_booker
The count of Bookings
where the Person
acted as booker.
totals.total_paid_as_booker
The total payments made when the Person
acted as a booker. In multi-currency accounts, the value is displayed in the default currency set for the account.
totals.booking_inquiry_count
The count of Booking Inquiries
.
id_type
The Person's ID type, nullable ENUM that could contain: id_card
, passport
, driver_license
, other
.
id_number
Number or series of identity document.
id_expiry_date
Expiration date of identity document in format yyyy-mm-dd
.
company_name
The Person's company name. For invocing purposes.
tax_number
Personal or company Tax/VAT number . For invoicing purposes.
diet_id
diet_id
ID of the Diet the Person is on.
diet.id
diet.id
ID of the Diet the Person is on.
diet.backoffice_title
diet.backoffice_title
Title of the Diet the Person is on.
diet.abbreviation
diet.abbreviation
Abbreviation of the Diet the Person is on.
is_guest
is_guest
A flag signaling whether the Person is a Guest in any booking.
is_booker
is_booker
A flag signaling whether the Person is a Booker, i.e. whether they have created any bookings.
created_at
Datetime at which the resource was created.
updated_at
Datetime at which the resource was last updated.
Endpoints
List all people
GET
https://api.bookinglayer.io/private/persons
Fetches a list of all people in the system. List can be filtered and sorted by custom parameters.
Query Parameters
Name | Type | Description |
---|---|---|
query | string | full-text search among various attributes. |
first_name | string | first_name contains. |
last_name | string | last_name contains. |
gender | string | possible options male, female. |
birth_date | date | date filter |
string | email contains. | |
is_guest | boolean | Filters persons that are a guest in at least one booking |
is_booker | boolean | Filters persons that have booked at least one booking |
sort_by | string | Possible, first_name, last_name, full_name, country, birth_date |
language_code | string | country ISO 3166-1 alpha-2 codes. |
nationality_code | string | country ISO 3166-1 alpha-2 codes. |
country_code | string | country ISO 3166-1 alpha-2 codes. |
phone_country_code | string | country ISO 3166-1 alpha-2 codes. |
Fetch a single Person
GET
https://api.bookinglayer.io/private/persons/{person_id}
Fetches a single Person from the system.
Path Parameters
Name | Type | Description |
---|---|---|
person_id* | UUID | ID of the desired person |
Create a new Person
POST
https://api.bookinglayer.io/private/persons
Creates and stores a new Person. If a Person with the specified email already exists that record will be updated instead.
Request Body
Name | Type | Description |
---|---|---|
email* | String | Email of the Person |
first_name | String | |
last_name | String | |
salutation | String | |
gender | String | |
birth_date | String | |
phone_country_id | String | |
phone | String | |
country_id | String | |
nationality_id | String | |
language_code | String | |
guest_group_id | String | |
diet_id | String | |
level_id | String | |
address_line_1 | String | |
address_line_2 | String | |
address_line_3 | String | |
zip_code | String | |
city | String | |
state | String | |
id_type | String |
Update an existing Person
PUT
https://api.bookinglayer.io/private/persons/{person_id}
Updates an existing person in the Bookinglayer system. Updating a person does not affect any Guest or Booker instances related to the person.
Path Parameters
Name | Type | Description |
---|---|---|
person_id* | UUID | ID of the Person |
Request Body
Name | Type | Description |
---|---|---|
Updates the Person email. | ||
first_name | string | Updates the Person first name. |
last_name | string | Updates the Person last name. |
salutation | string | Updates the Person salutation. |
gender | string | Updates the Person gender. |
birth_date | date | Updates the Person birth date. |
phone_country_code | Country alpha-2 code | Updates the Person phone country code and phone calling code accordingly. |
phone | string | Updates the Person phone. |
country_code | Country alpha-2 code | Updates the Person country. |
nationality_code | Country alpha-2 code | Updates the Person nationality. |
language_code | Country alpha-2 code | Updates the Person language. |
guest_group_id | int | Updates the Person guest group. |
diet_id | int | Updates the Person diet. |
level_id | int | Updates the Person level. |
address_line_1 | string | Updates the Person address line 1. |
address_line_2 | string | Updates the Person address line 2. |
address_line_3 | string | Updates the Person address line 3. |
zip_code | string | Updates the Person zip code. |
city | string | Updates the Person city. |
state | string | Updates the Person state. |
id_type | id_card, passport, driver_license or other | Updates the Person ID type. |
id_number | string | Updates the Person ID number. |
id_expiry_date | date | Updates the Person ID expiration date. |
tax_number | string | Updates the Person tax number. |
custom_fields | object | Updates the Person custom fields. |
Delete an existing Person
DELETE
https://api.bookinglayer.io/private/persons/{person_id}
Deletes an existing person. Any Person can be deleted, regardless if they are a Booker, Guest, both or none. Deleting a Person means they will no longer be accessible using the Persons endpoint, however their snapshots will still be available in the context of Bookings.
Path Parameters
Name | Type | Description |
---|---|---|
person_id* | UUID | ID of the Person |
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.
PersonCreated
PersonCreated
Sends a new Person ID via a webhook call when a Person gets created. If this Person is created during the creation of a Guest for a Booking the GuestCreated
webhook could be triggered as well for the same action.
PersonUpdated
PersonUpdated
Sends a Person ID via a webhook call when an existing Person gets updated. Updating a Guest also results in updating the Person that the Guest belongs to so the GuestUpdated
event would get dispatched at the same time.
PersonDeleted
PersonDeleted
Sends a Person ID and Booking ID via a webhook call when an existing Person gets deleted.
Last updated