How to use the Client API | Booxi Help Center

Use of this API requires a partner API Key. To obtain such a key, contact your Booxi representative.
Prior to use, consult Booxi's API fair use policy.
Remember that the URL at which you access the API depends on your hosting region. This article presents examples from a North American hosting only.
API documentation links:
- North America
- Europe

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

How to retrieve client records using the Booxi API

How to retrieve a client’s metadata using the Booxi API

How to use the STAFF API

How to use the Service API

How to use the Service Category API