Use Cases
      Back to home
      1. Knowledge Base
      2. Webhooks & APIs
      3. Use Cases

      How to Use the CLIENT API

      The following article provides an overview of the Client API and explains how to use each of its endpoints.

      Please take note that this API requires a partner API Key. If you haven’t been provided with such a key, please contact your Booxi representative.

       

      Be reminded that the URL at which you access the API depends on your hosting region. This article presents examples from a North American hosting.

       

      For North America For Europe
      api.booxi.com api.booxi.eu

      CRUD Endpoints

      GET /client

      Finds one or more client records that meet the provided parameters. Search can be performed using an external ID or identifiers such as first and last names, phone number or email address. Those search criteria cannot be mixed.

       

      To fetch client records use the GET /client endpoint as per the details and examples shown below. Your request must include one search criteria.

       

      Parameters

      Parameter Format Description
      moduleId string The id of the module to search in. This parameter is required when searching with an externalId. Otherwise, the parameter is optional.
      externalId string The external id of a client record in the module defined by moduleId. This parameter must be provided along with moduleId.
      merchantId integer The merchant id the client records are accessible to. This parameter is required when searching with contact info (name, phone number or email address). Otherwise, it is optional.
      firstName string The first name associated with the client record(s) to search for. First and last names must come in pairs. If one is provided, the other becomes mandatory.
      lastName string The last name associated with the client record(s) to search for. First and last names must come in pairs. If one is provided, the other becomes mandatory.
      email string The email address associated with the client record(s) to search for.
      phoneNumber string The home or mobile phone number associated with the client record(s) to search for.

       

      Request URL for the North America

      https://api.booxi.com/booking/v1/client

      Request URL for Europe

      https://api.booxi.eu/booking/v1/client

       

      cURL 

      Here’s an example of a query using the client’s name as search criteria. Notice that three parameters are passed, merchantId, firstName and lastName.

      curl -X GET 
      "https://api.booxi.com/booking/v1/client?merchantId=YOUR_MERCHANT_ID&firstName=CLIENT_FIRST_NAME&lastName=CLIENT_LAST_NAME" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"

      Note

      • The response only includes clientLinks when searching with a moduleId.
      • If there are too many results, only the first matching clients will be returned.

      Successful Response

      Here’s an example of a successful response.

      {
        "clients": [
          {
            "id": 1234567,
            "merchantId": 0001,
            "firstName": "First",
            "lastName": "Last",
            "email": "recipient@domain.ext",
            "homePhoneNumber": "+12223334444",
            "mobilePhoneNumber": "+12223334444",
            "dateOfBirth": {
              "day": 1,
              "month": 1,
              "year": 2000
            },
            "address": {
              "street": "street",
              "city": "city",
              "state": "state",
              "postalCode": "00000",
              "country": "country"
            },
            "gender": "Unknown"
          }
        ]
      }

      You can test this endpoint at the following links.

      For North America For Europe
      findClients findClients

      POST /client

      Create a new client record using the information provided in the request body. This endpoint doesn’t require any parameter.

       

      Request Body

      Field Format Description
      merchantId integer Id of the merchant the client is created for.
      firstName string New client’s first name.
      lastName string New client’s last name.
      dateOfBirth array New client’s date of birth as an array of strings. The array must contain the following fields:
      • day
      • month
      • year
      homePhoneNumber string New client’s home phone number.
      mobilePhoneNumber string New client’s mobile phone number.
      email string New client’s email address.
      address array New client’s address as an array of strings. The array must contain the following fields:
      • street
      • city
      • postalCode
      • state
      • country

       

      Example of a request body

      {
        "merchantId": 0001,
        "firstName": "First",
        "lastName": "Last",
        "dateOfBirth": {
          "day": 1,
          "month": 1,
          "year": 2000
        },
        "homePhoneNumber": "+12223334444",
        "mobilePhoneNumber": "+12223334444",
        "email": "recipient@domain.ext",
        "address": {
          "street": "street",
          "city": "city",
          "postalCode": "00000",
          "country": "country",
          "state": "state"
        }
      }

       

      Request URL for the North America

      https://api.booxi.com/booking/v1/client

      Request URL for the Europe

      https://api.booxi.eu/booking/v1/client

       

      cURL

      Here’s an example using the body request provided above.

      curl -X POST 
      "https://api.booxi.com/booking/v1/client" -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
      -H  "Content-Type: application/json" -d "{\"merchantId\":YOUR_MERCHANT_ID,\"firstName\":\"First\",\"lastName\":\"Last\",\"dateOfBirth\":{\"day\":1,\"month\":1,\"year\":2000},\"homePhoneNumber\":\"+1222333444\",\"mobilePhoneNumber\":\"+1222333444\",\"email\":\"recipient@domain.ext\",\"address\":{\"street\":\"street\",\"city\":\"city\",\"postalCode\":\"00000\",\"country\":\"country\",\"state\":\"state\"}}"

       

      Successful Response

      Here’s an example of a newly created client record.

      {
        "client": {
          "id": 1234567,
          "merchantId": 0001,
          "firstName": "First",
          "lastName": "Last"
        }
      }

       

      You can test this endpoint at the following links.

      For North America For Europe
      createClient createClient

      GET /client/{clientId}

      Retrieves the details of a specific client record.

       

      Parameters

      Parameter Format Description
      clientId integer The id of the client record to look for. This parameter is mandatory.

       

      Request URL for the North America

      https://api.booxi.com/booking/v1/client

      Request URL for the Europe

      https://api.booxi.eu/booking/v1/client

       

      cURL 

      Here’s an example of a valid query.

      curl -X GET 
      "https://api.booxi.com/booking/v1/client/1234567" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"

       

      Successful Response

      Here’s an example of a client record’s details.

      {
        "client": {
          "id": 1234567,
          "merchantId": 0001,
          "firstName": "First",
          "lastName": "Last",
          "email": "recipient@domain.ext",
          "homePhoneNumber": "+12223334444",
          "mobilePhoneNumber": "+12223334444",
          "metadata": {
            "memberTier": "vip"
          }
        }
      }

       

      You can test this endpoint at the following links.

      For North America For Europe
      getClient getClient

      PUT /client/{clientId}

      Update an existing client record using the information provided in the request body.

       

      Parameters

      Parameter Format Description
      clientId integer The id of the client record to update. This parameter is mandatory.

       

      Request Body

      Field Format Description
      firstName string Client’s first name.
      lastName string Client’s last name.
      dateOfBirth array Client’s date of birth as an array of strings. The array must contain the following fields:
      • day
      • month
      • year
      homePhoneNumber string Client’s home phone number.
      mobilePhoneNumber string Client’s mobile phone number.
      email string Client’s email address.
      gender string Client’s gender.
      address array Client’s address as an array of strings. The array must contain the following fields:
      • street
      • city
      • postalCode
      • state
      • country

       

      Note

      • The id, merchant id and metadata associated with a client record cannot be updated.
      • To leave a field unchanged, remove it from the request body.
      • To delete a field, set it to "" (string) and 0 (integer).

       

      Example of a request body

      {
        "firstName": "First",
        "lastName": "Last",
        "dateOfBirth": {
          "day": 1,
          "month": 1,
          "year": 2000
        },
        "homePhoneNumber": "+12223334444",
        "mobilePhoneNumber": "+12223334444",
        "email": "recipient@domain.ext",
        "gender": "Male",
        "address": {
          "street": "street",
          "city": "city",
          "postalCode": "00000",
          "country": "country",
          "state": "state"
        }
      }

       

      Request URL for the North America

      https://api.booxi.com/booking/v1/client/{clientId}

      Request URL for the Europe

      https://api.booxi.eu/booking/v1/client/{clientId}

       

      cURL 

      Here’s an example of a valid query.

      curl -X PUT
      "https://api.booxi.com/booking/v1/client" -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY" 
      -H  "Content-Type: application/json" -d "{\"merchantId\":YOUR_MERCHANT_ID,\"firstName\":\"First\",\"lastName\":\"Last\",\"dateOfBirth\":{\"day\":1,\"month\":1,\"year\":2000},\"homePhoneNumber\":\"+1222333444\",\"mobilePhoneNumber\":\"+1222333444\",\"email\":\"recipient@domain.ext\",\"gender\":\"Male\",\"address\":{\"street\":\"street\",\"city\":\"city\",\"postalCode\":\"00000\",\"country\":\"country\",\"state\":\"state\"}}"

       

      Successful Response

      The updated client record.

      {
        "client": {
          "id": 1234567,
          "merchantId": 0001,
          "firstName": "First",
          "lastName": "Last",
          "homePhoneNumber": "+12223334444",
          "mobilePhoneNumber": "+12223334444",
          "email": "recipient@domain.ext",
          "gender": "Male",
          "address": {
            "street": "street",
            "city": "city",
            "postalCode": "00000",
            "country": "country",
            "state": "state"
          }
          "metadata": {
            "memberTier": "vip"
          }
        }
      }

       

      You can test this endpoint at the following links.

      For North America For Europe
      updateClient updateClient

      DELETE /client/{clientId}

      Deletes a specific client record.

       

      Parameters

      Parameter Format Description
      clientId integer The id of the client record to delete This parameter is mandatory.

       

      Request URL for the North America

      https://api.booxi.com/booking/v1/client/{clientId}

      Request URL for the Europe

      https://api.booxi.eu/booking/v1/client/{clientId}

       

      cURL 

      Here’s an example of a valid query.

      curl -X DELETE
      "https://api.booxi.com/booking/v1/client/1234567" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"

       

      Successful Response

      Here’s an example of a deleted client record’s details.

      {
        "client": {
          "id": 1234567,
          "merchantId": 0001,
          "firstName": "First",
          "lastName": "Last",
          "email": "recipient@domain.ext",
          "homePhoneNumber": "+12223334444",
          "mobilePhoneNumber": "+12223334444",
          "dateOfBirth": {
            "day": 1,
            "month": 1,
            "year": 2000
          },
          "address": {
            "street": "street",
            "city": "city",
            "postalCode": "00000",
            "country": "country",
            "state": "state"
          }
        }
      }

       

      You can test this endpoint at the following links.

      For North America For Europe
      deleteClient deleteClient

      Modules

      Module links are associations between an external object, such as client, service or product, staff or store, and their equivalent in Booxi. Links can be used to store and retrieve external Id and metadata assigned to an object by using the Booxi API. Take note that the module must be configured and activated by Booxi before usage.

       

      GET /client/{clientId}/moduleLink/{moduleId}

      Retrieves the link configuration of a client record for a given integration module. 


      Note: if the integration module was never configured, a default client link, with empty values, will be returned instead.

       

      Parameters

      Parameter Format Description
      clientId integer The id of the client the module link is for.
      moduleId integer The id of the integration module the client is associated with.

       

      Request URL for the North America

      https://api.booxi.com/booking/v1/client/{clientId}/moduelLink/{moduleId}

      Request URL for the Europe

      https://api.booxi.eu/booking/v1/client/{clientId}/moduleLink/{moduleId}

       

      cURL 

      Here’s an example of a valid query.

      curl -X GET
      "https://api.booxi.com/booking/v1/client/1234567/moduleLink/1234567" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"

       

      Successful Response

      Here’s an example of a client link configuration for a specific module.

      {
        "link": {
          "moduleId": "payment",
          "clientId": 1234567,
          "externalId": "cust00001",
          "metadata": {
            "memberTier": "vip"
          },
          "createdOn": "2024-01-20T07:15:00Z",
          "modifiedOn": "2024-01-20T07:30:00Z"
        },
        "client": {
          "id": 1234567,
          "merchantId": 0001,
          "firstName": "First",
          "lastName": "Last",
          "email": "recipient@domain.ext",
          "homePhoneNumber": "+12223334444",
          "mobilePhoneNumber": "+12223334444",
          "metadata": {
            "memberTier": "vip"
          }
        }
      }

       

      You can test this endpoint at the following links.

      For North America For Europe
      getClientModuleLink getClientModuleLink

       

      PUT /client/{clientId}/moduleLink/{moduleId}

      Updates the link configuration of a client record for a given integration module. Use this endpoint to update or assign an externalId to an existing client record in Booxi.


      Note: If given, the metadata field provided in the request body will replace the existing one entirely. To avoid losing any data, it is recommended to copy the client link before updating any data.

       

      Parameters

      Parameter Format Description
      clientId integer The id of the client the module link is for.
      moduleId integer The id of the integration module the client is associated with.

       

      Example of a request body with custom metadata.

      {
        "externalId": "0003301",
        "metadata": {
          "region": "uptown",
          "memberTier": "vip",
          "region" : "uptown"
        }
      }

       

      Request URL for the North America

      https://api.booxi.com/booking/v1/client/{clientId}/moduelLink/{moduleId}

      Request URL for the Europe

      https://api.booxi.eu/booking/v1/client/{clientId}/moduleLink/{moduleId}

       

      cURL 

      Here’s an example of a valid query with custom metadata.

      curl -X PUT
      "https://api.booxi.com/booking/v1/client/1234567/moduleLink/1234567" 
      -H  "accept: application/json" 
      -H  "Booxi-PartnerKey: YOUR_PARTNER_API_KEY"
      -H  "Content-Type: application/json" -d "{\"externalId\":\"0033001\",\"metadata\":{\"memberTier\":\"vip\",\"region\":\"uptown\"}}"

       

      Successful JSON Response

      Here’s an example of a successful response:

      {
        "link": {
          "moduleId": "payment",
          "clientId": 1234567,
          "externalId": "cust00001",
          "metadata": {
            "memberTier": "vip",
            "region" : "uptown"
          },
          "createdOn": "2024-01-20T07:15:00Z",
          "modifiedOn": "2024-01-20T07:30:00Z"
        },
        "client": {
          "id": 1234567,
          "merchantId": 0001,
          "firstName": "First",
          "lastName": "Last",
          "email": "recipient@domain.ext",
          "homePhoneNumber": "+12223334444",
          "mobilePhoneNumber": "+12223334444",
          "metadata": {
            "memberTier": "vip",
            "region" : "uptown"
          }
        }
      }

       

      You can test this endpoint at the following links.

      For North America For Europe
      updateClientExternal updateClientExternal

       

      Limitations & Notes

      • This API shall not be used to generate reports or export data.
      • Modules must be configured and activated by Booxi before usage.

      References

      For more information about the Booxi APIs and their usage, please refer to the following links:

       

      Europe: https://api.booxi.eu/doc/booking.html

      Americas: https://api.booxi.com/doc/booking.html

      Where to find API keys:

      • Your Merchant API key can be found in the back office, section My Business / Details.
      • Your Partner API key must be requested to your Booxi Account Manager. The Partner API key must only be used in server-side (backend) code to keep it a secret.