How to Retrieve a Client’s Metadata Using the Booxi API

Additional information saved along a client's records can be retrieved using the Booxi API. An external ID and its associated metadata could be employed to synchronize your CRM with the content of a Booxi’s client record. The following article will present how to retrieve and update metadata from a client record.

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

Furthermore, your partner API key and webhook endpoint must have been configured/authorized for a module in order to access its linked data.

Be reminded that the URL you should use depends on your hosting region. This article presents examples from a North American hosting.

Finding the Module Data in a Webhook Event

If your webhook endpoint is authorized, the event associated with a new booking will include additional data. The module data will be found in the JSON under eventContent.clientLinks[YOUR_MODULE_ID].metadata for the object matching the moduleId.  If a booking has more than one client ( i.e. group reservation) the Booxi clientId should also match.

clientLinks
[
   ClientModuleLink
   {
      moduleId string
      clientId integer
      externalId string

      metadata Metadata
      {
         A series of string key/value pairs that further describe this object.
         These properties hold custom information about the object that is not directly 
         owned or used by Booxi. Metadata is commonly used to store merchant/partner      
         specific data (like an third party id) to the object to help with custom  
         integration.

         ex. "loyaltyTier": "member"
      }
      createdOn string($date-time)
      modifiedOn string($date-time)
   }
]

Retrieving the Module Link Data

To retrieve the module data for a client, use the client API GET /client/{clientId}/moduleLink/{moduleId}/ by providing a Booxi clientId and moduleId.

Request URL for North America

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

cURL

curl -X GET
"https://api.booxi.com/booking/v1/client/{clientId}/moduleLink/{moduleId}" 
-H  "accept: application/json"
-H  "Booxi-PartnerKey: YOUR_PARTNER_KEY"

Updating the Module Link Data

To update the data, use the PUT /client/{clientId}/moduleLink/{moduleId}/ API by providing the Booxi clientId and moduleId associated with the entry you wish to update. Take note that this operation will overwrite any previous data. It is recommended to copy the data before making any changes.

Request URL for North America

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

cURL

curl -X PUT
"https://api.booxi.com/booking/v1/client/{clientId}/moduleLink/{moduleId}" 
-H  "accept: application/json"
-H  "Booxi-PartnerKey: YOUR_PARTNER_KEY"
-d "{\"externalId\":\"{externalId}\",\"metadata\":{\"Your metadata here}}"

You can test this API at the following links.

CRM Synchronization Use Case

The following is provided as an example only. There are many different ways to approach the problem.

• Listen to the webhook events to capture new appointment bookings (online and offline).
• Check if the externalId found in the module link data matches one of your CRM customer Id.
• If it matches, a returning customer booked an appointment. No changes are required in the Booxi client record but you might need to update your CRM entry.
• If it doesn’t match, add a new customer in your CRM and use the client API to update the Booxi client record by setting its externalId.

Supported Modules

• Cegid Y2
• Client-specific module

Limitations

• The authentication method requires a secure environment.
• The endpoint must not be exposed on a webpage but rather server side.
• The webhook endpoint must be configured/authorized to access a module.

References

For more information about 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.