Clients

Overview

This resource represents the Clients which effectively are the actual travelers (guests) that are related to Bookings.

Parameters

OAuth Scopes:

clients_read

Group	Name	Type	Read/Write	Description
account	Integer	Read	Account's ID related to the Client
id	Integer	Read	Client's id.
company	String	Read	Client's company name.
fullname	String	Read	Client's fullname.
firstname	String	Read	Client's first name.
lastname	String	Read	Client's last name.
notes	Text	Read	Client's notes.
passport	String	Read	Client's passport id.
preferred_locale	String	Read	Client's contact language preference.
vat_number	String	Read	Client's company vat number.
created_at	Time	Read	Client's create time.
updated_at	Time	Read	Client's update time.
forget_me_at	Time	Read	Refer to GDPR guide.
processing_restricted_at	Time	Read	Refer to GDPR guide
addresses		Array	Read	Array of client's addresses.
address1	String	Read	Client's first address.
address2	String	Read	Client's second address.
city	String	Read	Client's city.
country_code	String	Read	Client's country code, list of codes is available at wikipedia.
label	String	Read	Address label.
state	String	Read	Client's state.
zip	String	Read	Client's zip.
emails		Array	Read	Array of client's emails.
email	String	Read	Client's email.
label	String	Read	Email label.
phones		Array	Read	Array of client's phone numbers.
label	String	Read	Phone label.
number	String	Read	Client's number.

clients_write

Group	Name	Type	Read/Write	Description	Constraints
account	Integer	Read	Account's ID related to the Client
company	String	Read/Write	Client's company name.
fullname	String	Read/Write	Required. Client's fullname.	Maximum length: 150. Use either fullname or firstname and lastname
firstname	String	Read/Write	Client's first name.	Maximum length: 150. Use either fullname or firstname and lastname
lastname	String	Read/Write	Client's last name.	Maximum length: 150. Use either fullname or firstname and lastname
notes	Text	Read/Write	Client's notes. (5000 characters max)	Maximum length: 5000
passport	String	Read/Write	Client's passport id. (50 characters max)	Maximum length: 50
preferred_locale	String	Read/Write	Client's contact language preference.	Must be one of account's selected_locales
vat_number	String	Read/Write	Client's company vat number.
created_at	Time	Read	Client's create time.
updated_at	Time	Read	Client's update time.
addresses		Array	Read/Write	Array of client's addresses.
address1	String	Read/Write	Client's first address.	Maximum length: 100, cannot contain non-printable characters
address2	String	Read/Write	Client's second address.	Maximum length: 100, cannot contain non-printable characters
city	String	Read/Write	Client's city.	Maximum length: 100, required if city is present, cannot contain non-printable characters
country_code	String	Read/Write	Client's country code, list of codes is available at wikipedia.	Must be a country code enum
label	String	Read/Write	Address label.	Required (if the element is present in addresses array)
state	String	Read/Write	Client's state.	Maximum length: 100, cannot contain non-printable characters
zip	String	Read/Write	Client's zip.	Maximum length: 15, cannot contain non-printable characters
emails		Array	Read/Write	Array of client's emails.
email	String	Read/Write	Client's email.	Required, must be in email format (if the element is present in emails array)
label	String	Read/Write	Email label.	Required (if the element is present in emails array)
phones		Array	Read/Write	Array of client's phone numbers.
label	String	Read/Write	Phone label.	Required, must be in email format (if the element is present in phones array)
number	String	Read/Write	Client's number.	Required, must be in phone number format (if the element is present in phones array)

Preferred locale

Client preferred locale should be one of the following codes: af ar bg ca cs da de el en es fi fr hr hu id is it iw ja ka ko lt lv mk nb nl pl pt ro ru sk sl sr sv th uk zh-CN zh-TW.

If a different locale is provided, we suggest falling back to one of the supported locales from the list above.

Grouped attributes

First set of attributes in array group will always be used as default address, email or phone.

List clients

List all clients for a given account.

GET /clients

OAuth Scopes:

clients_read / clients_write

response.json

{
  "links": {
    "clients.account": "https://www.bookingsync.com/api/v3/accounts/{clients.account}"
  },
  "clients": [
    {
      "links": {
        "account": 1
      },
      "id": 1,
      "addresses": [
        {
          "id": 1,
          "client_id": 1,
          "label": "default",
          "address1": "Kutch Stravenue",
          "address2": "Building 1",
          "city": "North Jacey",
          "state": "Illinois",
          "zip": "01363-9579",
          "country_code": "US",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true
        }
      ],
      "emails": [
        {
          "id": 1,
          "client_id": 1,
          "label": "default",
          "email": "clementina_kling@example.com",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        }
      ],
      "phones": [
        {
          "id": 1,
          "client_id": 1,
          "label": "phone",
          "number": "(153)070-6105",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        },
        {
          "id": 2,
          "client_id": 1,
          "label": "mobile",
          "number": "(153)070-6106",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        },
        {
          "id": 3,
          "client_id": 1,
          "label": "fax",
          "number": "(153)070-6107",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        }
      ],
      "created_at": "2014-12-28T15:19:27Z",
      "updated_at": "2015-02-02T11:07:45Z",
      "fullname": "Clementina Kling",
      "firstname": "Clementina",
      "lastname": "Kling",
      "notes": "",
      "passport": "AHJ4678956",
      "preferred_locale": "en",
      "company": "Great Company",
      "vat_number": "ES65465465"
    }
  ],
  "meta": {}
}

Get a single client

Returns a single client identified by ID.

GET /clients/:client_id

OAuth Scopes:

clients_read / clients_write

response.json

{
  "links": {
    "clients.account": "https://www.bookingsync.com/api/v3/accounts/{clients.account}"
  },
  "clients": [
    {
      "links": {
        "account": 1
      },
      "id": 1,
      "addresses": [
        {
          "id": 1,
          "client_id": 1,
          "label": "default",
          "address1": "Kutch Stravenue",
          "address2": "Building 1",
          "city": "North Jacey",
          "state": "Illinois",
          "zip": "01363-9579",
          "country_code": "US",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true
        }
      ],
      "emails": [
        {
          "id": 1,
          "client_id": 1,
          "label": "default",
          "email": "clementina_kling@example.com",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        }
      ],
      "phones": [
        {
          "id": 1,
          "client_id": 1,
          "label": "phone",
          "number": "(153)070-6105",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        },
        {
          "id": 2,
          "client_id": 1,
          "label": "mobile",
          "number": "(153)070-6106",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        },
        {
          "id": 3,
          "client_id": 1,
          "label": "fax",
          "number": "(153)070-6107",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        }
      ],
      "created_at": "2014-12-28T15:19:27Z",
      "updated_at": "2015-02-02T11:07:45Z",
      "fullname": "Clementina Kling",
      "firstname": "Clementina",
      "lastname": "Kling",
      "notes": "",
      "passport": "AHJ4678956",
      "preferred_locale": "en",
      "company": "Great Company",
      "vat_number": "ES65465465"
    }
  ],
  "meta": {}
}

Create a new client

Returns a newly created client.

POST /clients

OAuth Scopes:

clients_write

request.json

{
  "clients": [
    {
      "links": {
        "account": 1
      },
      "id": 1,
      "addresses": [
        {
          "id": 1,
          "client_id": 1,
          "label": "default",
          "address1": "Kutch Stravenue",
          "address2": "Building 1",
          "city": "North Jacey",
          "state": "Illinois",
          "zip": "01363-9579",
          "country_code": "US",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true
        }
      ],
      "emails": [
        {
          "id": 1,
          "client_id": 1,
          "label": "default",
          "email": "clementina_kling@example.com",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        }
      ],
      "phones": [
        {
          "id": 1,
          "client_id": 1,
          "label": "phone",
          "number": "(153)070-6105",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        },
        {
          "id": 2,
          "client_id": 1,
          "label": "mobile",
          "number": "(153)070-6106",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        },
        {
          "id": 3,
          "client_id": 1,
          "label": "fax",
          "number": "(153)070-6107",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        }
      ],
      "created_at": "2014-12-28T15:19:27Z",
      "updated_at": "2015-02-02T11:07:45Z",
      "fullname": "Clementina Kling",
      "firstname": "Clementina",
      "lastname": "Kling",
      "notes": "",
      "passport": "AHJ4678956",
      "preferred_locale": "en",
      "company": "Great Company",
      "vat_number": "ES65465465"
    }
  ]
}

response.json

{
  "links": {
    "clients.account": "https://www.bookingsync.com/api/v3/accounts/{clients.account}"
  },
  "clients": [
    {
      "links": {
        "account": 1
      },
      "id": 1,
      "addresses": [
        {
          "id": 1,
          "client_id": 1,
          "label": "default",
          "address1": "Kutch Stravenue",
          "address2": "Building 1",
          "city": "North Jacey",
          "state": "Illinois",
          "zip": "01363-9579",
          "country_code": "US",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true
        }
      ],
      "emails": [
        {
          "id": 1,
          "client_id": 1,
          "label": "default",
          "email": "clementina_kling@example.com",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        }
      ],
      "phones": [
        {
          "id": 1,
          "client_id": 1,
          "label": "phone",
          "number": "(153)070-6105",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        },
        {
          "id": 2,
          "client_id": 1,
          "label": "mobile",
          "number": "(153)070-6106",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        },
        {
          "id": 3,
          "client_id": 1,
          "label": "fax",
          "number": "(153)070-6107",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        }
      ],
      "created_at": "2014-12-28T15:19:27Z",
      "updated_at": "2015-02-02T11:07:45Z",
      "fullname": "Clementina Kling",
      "firstname": "Clementina",
      "lastname": "Kling",
      "notes": "",
      "passport": "AHJ4678956",
      "preferred_locale": "en",
      "company": "Great Company",
      "vat_number": "ES65465465"
    }
  ],
  "meta": {}
}

Update a client

Grouped attributes

Please note that updating grouped attributes requires the full array to be re-sent, to avoid data loss. In below example all phones elements are present.

Returns an updated client identified by ID.

PUT /clients/:client_id

OAuth Scopes:

clients_write

request.json

{
  "clients": [
    {
      "links": {
        "account": 1
      },
      "id": 1,
      "addresses": [
        {
          "id": 1,
          "client_id": 1,
          "label": "default",
          "address1": "Kutch Stravenue",
          "address2": "Building 1",
          "city": "North Jacey",
          "state": "Illinois",
          "zip": "01363-9579",
          "country_code": "US",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true
        }
      ],
      "emails": [
        {
          "id": 1,
          "client_id": 1,
          "label": "default",
          "email": "clementina_kling@example.com",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        }
      ],
      "phones": [
        {
          "id": 1,
          "client_id": 1,
          "label": "phone",
          "number": "(153)070-6105",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        },
        {
          "id": 2,
          "client_id": 1,
          "label": "mobile",
          "number": "(153)070-6106",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        },
        {
          "id": 3,
          "client_id": 1,
          "label": "fax",
          "number": "(153)070-6107",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        }
      ],
      "created_at": "2014-12-28T15:19:27Z",
      "updated_at": "2015-02-02T11:07:45Z",
      "fullname": "Clementina Kling",
      "firstname": "Clementina",
      "lastname": "Kling",
      "notes": "",
      "passport": "AHJ4678956",
      "preferred_locale": "en",
      "company": "Great Company",
      "vat_number": "ES65465465"
    }
  ]
}

response.json

{
  "links": {
    "clients.account": "https://www.bookingsync.com/api/v3/accounts/{clients.account}"
  },
  "clients": [
    {
      "links": {
        "account": 1
      },
      "id": 1,
      "addresses": [
        {
          "id": 1,
          "client_id": 1,
          "label": "default",
          "address1": "Kutch Stravenue",
          "address2": "Building 1",
          "city": "North Jacey",
          "state": "Illinois",
          "zip": "01363-9579",
          "country_code": "US",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true
        }
      ],
      "emails": [
        {
          "id": 1,
          "client_id": 1,
          "label": "default",
          "email": "clementina_kling@example.com",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        }
      ],
      "phones": [
        {
          "id": 1,
          "client_id": 1,
          "label": "phone",
          "number": "(153)070-6105",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        },
        {
          "id": 2,
          "client_id": 1,
          "label": "mobile",
          "number": "(153)070-6106",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        },
        {
          "id": 3,
          "client_id": 1,
          "label": "fax",
          "number": "(153)070-6107",
          "country_code": "VG",
          "created_at": "2018-12-04T12:33:36Z",
          "updated_at": "2018-12-04T12:33:36Z",
          "canceled_at": null,
          "primary": true,
          "locked": null
        }
      ],
      "created_at": "2014-12-28T15:19:27Z",
      "updated_at": "2015-02-02T11:07:45Z",
      "fullname": "Clementina Kling",
      "firstname": "Clementina",
      "lastname": "Kling",
      "notes": "",
      "passport": "AHJ4678956",
      "preferred_locale": "en",
      "company": "Great Company",
      "vat_number": "ES65465465"
    }
  ],
  "meta": {}
}