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 [email protected], places a Booking on a Monday with the phone number [phone], and subsequently makes another Booking on a Wednesday with the number [phone], the latter number ([phone]) 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": "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"
}

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

ID of the Diet the Person is on.

diet.id

ID of the Diet the Person is on.

diet.backoffice_title

Title of the Diet the Person is on.

diet.abbreviation

Abbreviation of the Diet the Person is on.

is_guest

A flag signaling whether the Person is a Guest in any booking.

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
email	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.

200: OK

{
    "data": [
        {
            "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": false,
            "created_at": "2017-06-20T15:45:05+00:00",
            "updated_at": "2020-04-15T13:08:58+00:00"
        }
    ],
    "links": {
        "first": "https://api.bookinglayer.io/private/persons?page=1",
        "last": "https://api.bookinglayer.io/private/persons?page=10",
        "prev": "https://api.bookinglayer.io/private/persons?page=3",
        "next": "https://api.bookinglayer.io/private/persons?page=5"
    }
}

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

200: OK

{
    "data": {
        "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": false,
        "created_at": "2017-06-20T15:45:05+00:00",
        "updated_at": "2020-04-15T13:08:58+00:00"
    }
}

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

200: OK

{
    "data": {
        "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": false,
        "created_at": "2017-06-20T15:45:05+00:00",
        "updated_at": "2020-04-15T13:08:58+00:00"
    }
}

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
email	email	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.

200: OK

{
    "data": {
        "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": false,
        "created_at": "2017-06-20T15:45:05+00:00",
        "updated_at": "2020-04-15T13:08:58+00:00"
    }
}

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

204: No Content

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

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.

{
    "event": "PersonCreated",
    "data": {
        "id": "9f89d012-5bc1-4c1e-8637-b545f2b85098"
    }
}

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.

{
    "event": "PersonUpdated",
    "data": {
        "id": "9f89d012-5bc1-4c1e-8637-b545f2b85098"
    }
}

PersonDeleted

Sends a Person ID and Booking ID via a webhook call when an existing Person gets deleted.

    "event": "PersonDeleted",
    "data": {
        "id": "9f89d012-5bc1-4c1e-8637-b545f2b85098"
    }
}