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": "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"
}

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.

{
    "data": [
        {
            "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": 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

{
    "data": {
        "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": 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

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

{
    "data": {
        "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": 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

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"
    }
}
PreviousWebhooksNextGuests

Last updated