Clients

  1. Overview
  2. List clients
  3. Get a single client
  4. Create a new client
  5. Update a client

Overview

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

Parameters

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

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

Response

{
  "links": {
    "clients.account": "https://www.bookingsync.com/api/v3/accounts/{clients.account}"
  },
  "clients": [
    {
      "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
        }
      ],
      "company": "Great Company",
      "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
        }
      ],
      "firstname": "Clementina",
      "fullname": "Clementina Kling",
      "lastname": "Kling",
      "notes": "",
      "passport": "AHJ4678956",
      "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
        }
      ],
      "preferred_locale": "en",
      "vat_number": "ES65465465",
      "created_at": "2014-12-28T15:19:27Z",
      "updated_at": "2015-02-02T11:07:45Z",
      "links": {
        "account": 1
      }
    }
  ],
  "meta": {
  }
}

Get a single client

Returns a single client identified by ID.

GET /clients/:client_id

Response

{
  "links": {
    "clients.account": "https://www.bookingsync.com/api/v3/accounts/{clients.account}"
  },
  "clients": [
    {
      "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
        }
      ],
      "company": "Great Company",
      "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
        }
      ],
      "firstname": "Clementina",
      "fullname": "Clementina Kling",
      "lastname": "Kling",
      "notes": "",
      "passport": "AHJ4678956",
      "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
        }
      ],
      "preferred_locale": "en",
      "vat_number": "ES65465465",
      "created_at": "2014-12-28T15:19:27Z",
      "updated_at": "2015-02-02T11:07:45Z",
      "links": {
        "account": 1
      }
    }
  ],
  "meta": {
  }
}

Create a new client

Returns a newly created client.

POST /clients

Example JSON request

{
  "clients": [
    {
      "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
        }
      ],
      "company": "Great Company",
      "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
        }
      ],
      "firstname": "Clementina",
      "fullname": "Clementina Kling",
      "lastname": "Kling",
      "notes": "",
      "passport": "AHJ4678956",
      "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
        }
      ],
      "preferred_locale": "en",
      "vat_number": "ES65465465",
      "created_at": "2014-12-28T15:19:27Z",
      "updated_at": "2015-02-02T11:07:45Z",
      "links": {
        "account": 1
      }
    }
  ]
}

Response

{
  "links": {
    "clients.account": "https://www.bookingsync.com/api/v3/accounts/{clients.account}"
  },
  "clients": [
    {
      "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
        }
      ],
      "company": "Great Company",
      "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
        }
      ],
      "firstname": "Clementina",
      "fullname": "Clementina Kling",
      "lastname": "Kling",
      "notes": "",
      "passport": "AHJ4678956",
      "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
        }
      ],
      "preferred_locale": "en",
      "vat_number": "ES65465465",
      "created_at": "2014-12-28T15:19:27Z",
      "updated_at": "2015-02-02T11:07:45Z",
      "links": {
        "account": 1
      }
    }
  ],
  "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

Example JSON request

{
  "clients": [
    {
      "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
        }
      ],
      "company": "Great Company",
      "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
        }
      ],
      "firstname": "Clementina",
      "fullname": "Clementina Kling",
      "lastname": "Kling",
      "notes": "",
      "passport": "AHJ4678956",
      "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
        }
      ],
      "preferred_locale": "en",
      "vat_number": "ES65465465",
      "created_at": "2014-12-28T15:19:27Z",
      "updated_at": "2015-02-02T11:07:45Z",
      "links": {
        "account": 1
      }
    }
  ]
}

Response

{
  "links": {
    "clients.account": "https://www.bookingsync.com/api/v3/accounts/{clients.account}"
  },
  "clients": [
    {
      "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
        }
      ],
      "company": "Great Company",
      "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
        }
      ],
      "firstname": "Clementina",
      "fullname": "Clementina Kling",
      "lastname": "Kling",
      "notes": "",
      "passport": "AHJ4678956",
      "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
        }
      ],
      "preferred_locale": "en",
      "vat_number": "ES65465465",
      "created_at": "2014-12-28T15:19:27Z",
      "updated_at": "2015-02-02T11:07:45Z",
      "links": {
        "account": 1
      }
    }
  ],
  "meta": {
  }
}