How to call on the API Endpoints

URLs

EU: https://platform.phorest.com/third-party-api-server/api/business/

US/AUS: https://platform-us.phorest.com/third-party-api-server/api/business/

DEV environment: https://api-gateway-dev.phorest.com/third-party-api-server/api/business/


Appointments Endpoint

Retrieving the list of appointments and checking the activationState will tell you whether it is confirmed or not, you can use the endpoint

http://developer.phorest.com/#!/Appointments/updateAppointment and use key/value "activationState": "ACTIVE"

activationState: ACTIVE, RESERVED, CANCELED

List of Errors seen on Appointments/ Bookings Endpoints

The bookings are in UTC time (i.e for a salon based in Canada - If a booking is made at 13:30 it needs to use the time 18:30 because Canada is 5 hours behind).

Here is the full list of issues when trying to book an appointment with the API:

  • 'STAFF_UNQUALIFIED'

The staff you have tried to use is not qualified for the service you are using.

  • 'STAFF_REQUESTED’

When the client wants to request a specific staff member for the appointment.


Seen on those endpoints:

- http://developer.phorest.com/#!/Appointments/getAppointments

- http://developer.phorest.com/#!/Appointments/confirmAppointments

- http://developer.phorest.com/#!/Appointments/updateAppointment

- http://developer.phorest.com/#!/Appointments/checkInAppointment

- http://developer.phorest.com/#!/Appointments/findAvailableAppointmentTimes

- http://developer.phorest.com/#!/Booking/createBooking

Example:

If "staffRequest" is set to true If "staffRequest" is set to false

When you create an appointment you can request a staff member (this sets staffRequest to true (see screenshot).  So say a client wants her hair cut with Lisa so she requests Lisa. If you try to move this appointment to a different staff member later(move it to staff John) then you’ll get STAFF_REQUESTED error because the client/user requested the original staff member(Lisa) not the new staff remember you are moving the appointment to.

2.png

When the appointment time moves to another time on the same day or another time on different days the error comes up. The error will only happen for changing staff when clients have already requested that staff member.  Moving to a different day/time could give you one of these errors:

- 'CLIENT_ALREADY_BOOKED_THIS_TIME'

- 'STAFF_NOT_WORKING' = staff not rostered for the day

  • 'MACHINE_DOUBLE_BOOKED'  = there are no more machines available for treatments - Check machines and rooms are correct for each service  http://developer.phorest.com/#!/Service/getBranchServices
  • 'ROOM_UNSUITABLE'  = room is not suitable to the type of treatment - Check machines and rooms are correct for each service  http://developer.phorest.com/#!/Service/getBranchServices
  • 'MACHINE_UNSUITABLE' 
  • 'SERVICE_ALREADY_BOOKED_THIS_DAY' 
  • 'INTERNET_BOOKING_ALREADY_BOOKED'
  • 'SERVICE_ALREADY_BOOKED_THIS_DAY',  = client is already booked for the same day
  • 'CLIENT_ALREADY_BOOKED_THIS_TIME'  = client is already booked for the slot appointment for the same time - You can check the /appointment endpoint or /client-service-history endpoint
  • 'STAFF_NOT_WORKING' = staff not rostered for the day
  • 'MIN_DAYS_BETWEEN_SESSIONS_NOT_EXCEEDED' 
  • 'MAX_DAYS_BETWEEN_SESSIONS_EXCEEDED' 
  • 'SPECIAL_OFFER_BEFORE_START_DATE' 
  • 'SPECIAL_OFFER_AFTER_END_DATE' 
  • 'SPECIAL_OFFER_NOT_ALLOWED_TIME'
  • 'SPECIAL_OFFER_MAX_CONCURRENT_EXCEEDED' 
  • 'SPECIAL_OFFER_MAX_PER_DAY_EXCEEDED' 
  • ' SPECIAL_OFFER_STAFF_EXCLUDED' 

 

ENDPOINTS WHEN THOSE ERRORS CAN COME UP

Check staff are not disqualified for a service http://developer.phorest.com/#!/Service/getBranchServices

Check machines and rooms are correct for each service  http://developer.phorest.com/#!/Service/getBranchServices

Check Special offer settings before creating a booking http://developer.phorest.com/#!/Service_Special_Offers/getServiceSpecialOffers

Check available appointment times before booking http://developer.phorest.com/#!/Appointments/findAvailableAppointmentTimes

Client Endpoint
HOW TO CREATE A CLIENT ON PHOREST SYSTEM HOW TO UPDATE A CLIENT ON PHOREST SYSTEM

Method: POST > Create Client for a business

Endpoint: /third-party-api-server/api/business/{businessId}/client

Postman URL:  https://platform.phorest.com/third-party-api-server/api/business/<<insert business_id here>>/client  

Note: To create a client, remove client_id from the body request.

Body request

{
"address": {
 "city": "Toronto",
 "country": "Canada",
 "postalCode": "",
 "state": "Toronto",
 "streetAddress1": "SomeStreet",
 "streetAddress2": "SomeTown"
},
"archived": false,
"banned": false,
"birthDate": "1975-08-01",
"clientCategoryIds": [
  "sV-l8hImJQDBdpFGFGB1bA"
],
"clientSince": "2021-08-01T14:21:48.487Z",
"createdAt": "2021-08-01T14:21:48.487Z",
"creditAccount": {
 "creditDays": 5,
 "creditLimit": 502.32,
 "outstandingBalance": 0
},
"deleted": false,
"email": "test2@home.com",
"emailMarketingConsent": true,
"emailReminderConsent": true,
"firstName": "Eamonn2",
"gender": "MALE",
"landLine": 35318345657,
"lastName": "Phorest",
"mobile": 189654879229145,
"notes": "sample",
"smsMarketingConsent": true,
"smsReminderConsent": true,
"updatedAt": "2021-10-01T14:21:48.487Z",
"version": 1
}

Response

{
   "clientId": "igK6P6lu40g3UeT_zhmJhw",
   "version": 1,
   "firstName": "Amanda",
   "lastName": "Doe",
   "mobile": "1234871229345",
   "landLine": "35312345667",
   "email": "test@phorest.com",
   "createdAt": "2021-10-04T09:39:46.000Z",
   "updatedAt": "2021-10-04T09:39:46.000Z",
   "address": {
       "streetAddress1": "Test",
       "streetAddress2": "Test2",
       "city": "Toronto",
       "state": "Toronto",
       "postalCode": "",
       "country": "Canada"
   },
   "birthDate": "2021-10-01",
   "clientSince": "2021-10-01T14:21:48.000Z",
   "gender": "FEMALE",
   "notes": "sample",
   "smsMarketingConsent": true,
   "emailMarketingConsent": true,
   "smsReminderConsent": true,
   "emailReminderConsent": true,
   "creditAccount": {
       "outstandingBalance": 0,
       "creditDays": 0,
       "creditLimit": 500.00
   },
   "archived": false,
   "deleted": false,
   "banned": false,
   "clientCategoryIds": []
}

Client created on Phorest System

mceclip0.png

Client Courses Endpoint
HOW TO GET A CLIENT COURSE HOW TO UPDATE A CLIENT COURSE ON PHOREST SYSTEM

Note: Client Course is not the same as Course. A Course is the package to be sold, whereas a Client Course is 1 Course purchased and assigned to a client.

Method: GET > Get paginated list of client courses for a business. Client courses may be filtered by client_id

Endpoint: /third-party-api-server/api/business/{businessId}/clientcourse

Postman URL:  https://platform.phorest.com/third-party-api-server/api/business/<<insert businessId here>>/clientcourse?includeArchived=true  

Note: To GET archived salons use the flag includeArchived=true

CSV Export Job Endpoint
HOW TO CREATE CVS EXPORT JOB HOW TO RETURN A CVS EXPORT JOB

Method: POST > Create CSV Export Job for a business

Endpoint:  /third-party-api-server/api/business/{businessId}/branch/{branchId}/csvexportjob

Postman URL:  https://platform.phorest.com/third-party-api-server/api/business/<<insert business_id here>>/branch/<<insert branch_id here>>/csvexportjob  


Note:
  • You can pull all transactions for a branch over a date range. Get the data that is used to generate the Phorest Sales Transactions Report (found in Manager -> Reports -> Additional Reports -> Sales Transactions). 
  • This request will generate the jobId
  • The Phorest API can be used to extract the following jobs:
    1. TRANSACTIONS_CSs - containing all transaction data
    2. SUNDRIES_CSV - Sundries is just petty cash sales in the salon
    3. DATEV_CSV - Datev is for exporting financial data in Germany to import into accountancy software
    4. CLIENT_COURSES_CSV - Client course data

Body request

Note: This request will generate the jobID

{
 "failureReason": "No records found",
 "finishFilter": "2021-10-21",
 "finished": "2021-10-21T13:37:13.836Z",
 "jobId": "hui", (not necessary to post as it will create the jobId anyway)
 "jobStatus": "DONE",
 "jobType": "CLIENT_COURSES_CSV",
 "startFilter": "2021-10-21",
 "started": "2021-10-21T13:37:13.836Z",
 "succeededRows": 492,
 "tempCsvExternalUrl": "https://eu1-mem.s3-eu-west-1.amazonaws.com/mem-prd/business/eTC3QY5W3p_HmGHezKfxJw/csvexport",
 "totalRows": 530
}

Response

{
   "jobId": "vfvLSzpUP2dIvwR6kGw8Fg",
   "jobType": "CLIENT_COURSES_CSV",
   "jobStatus": "SCHEDULED",
   "startFilter": "2021-10-21",
   "finishFilter": "2021-10-21"
}
Product Endpoint - Q&A's
Products x Stock Update Add sizes (S,M,L) instead measures(ml, g, l)
  • “ Is it possible to synchronise product stock in the Phorest system with the client website store?” The client wants that stock is deducted from their website if a sale is made in-salon and vice versa".
  • " Can you send me further instructions on which API you'd like me to add to the WordPress Woocommerce cart for automatic inventory updates? What would be the best/simplest way to do so with your particular system? Many companies have installation plug-ins that install the connections automatically."
  • " One of the key things we are trying to achieve is inventory sync between Phorest and Shopify. Essentially when someone purchases a product through the website that the inventory is depleted correctly and the sale is associated with that customer's record in Phorest.

To update the stock on the client website and in the Phorest system you can build something using the products endpoint and add the correct product and create a sale using the purchase endpoint

The value of the productId key on the product endpoint  /third-party-api-server/api/business/{businessId}/branch/{branchId}/product  is what you post as value for the
branchProductId  key in the body of the endpoint the purchase endpoint  /third-party-api-server/api/business/{businessId}/branch/{branchId}/purchase .

To automatically subtract from the stock, the quantity key needs to be supplied.

Please see the link below for more information: Integrating 3rd Party E-Commerce Solutions

Purchase Endpoint
HOW TO CREATE A PURCHASE FOR CLIENT SERIES/ COURSES Custom Payment Types

Method: POST > Create a purchase associated with a branch

Endpoint: /third-party-api-server/api/business/{businessId}/branch/{branchId}/purchase

Postman URL:  https://platform.phorest.com/third-party-api-server/api/business/<<insert business_id here>>/branch/<<insert branch_id here>>/purchase  


Note:
  • The series/courses cannot be purchased using a future date.
  • Changing the purchase date on the API request won’t move the actual purchase.
  • You’ll also need to change the "number" key: "HGiomh6k90GJVFDYHJ", for each request. Just change the number to something random.
  • The Phorest System has a date picker in the client series/courses section which allows you to set the purchase date to any date, this date picker only sets a purchase date on client series/courses but it doesn’t actually move the purchase date. Clients are still going to be charged on the date of the purchase.

Body Request

{
 "number": "HGiomh6k90GJVFDYHJ",
   "clientId": "wR73bNIyT8M6KLORmnDZnw",
   "payments": [{
       "amount": 800.0,
       "paymentTypeId": "1tXBjwGxQ3gACGVxpgjoXg",
       "type": "CREDIT"
   }],
   "items": [{
       "courseId": "JL_8MDctZVqj9BDyMPlcDA",
       "price": 800.0,
       "staffId": "j45taiPxpytBrd3CTZk4vw",
       "quantity": 1
   }]
}

Response

{
 "purchaseId": "bPc_0c283ET1ra8cloj9gQ",
   "number": "HGiomh6k90GJVFDYHJ",
   "transactionNumber": "434",
   "clientId": "wR73bNIyT8M6KLORmnDZnw",
   "payments": [
       {
           "paymentId": "zkMrzDvPgTqkVAgph_xjig",
           "type": "CREDIT",
           "amount": 800.00
       }
   ],
   "items": [
       {
           "purchaseItemId": "7Urc_G2K2ZwyimIlPWhfKQ",
           "description": "Unlimited Membership",
           "price": 800.00,
           "courseId": "JL_8MDctZVqj9BDyMPlcDA",
           "staffId": "j45taiPxpytBrd3CTZk4vw",
           "details": {
               "totalAmount": 800.00,
               "taxAmount": 0.00,
               "taxIncluded": false,
               "taxRates": [
                   {}
               ]
           },
           "childPurchaseItems": [
               {
                   "purchaseItemId": "J9tgQ6GusnAbV9UqRSZJtQ",
                   "description": "Unlimited Membership - Blow Dry",
                   "price": 800.00,
                   "staffId": "j45taiPxpytBrd3CTZk4vw",
                   "details": {
                       "totalAmount": 800.00,
                       "taxAmount": 0.00,
                       "taxIncluded": false,
                       "taxRates": [
                           {
                               "name": "Sales Tax",
                               "rate": 0.0000
                           }
                       ]
                   },
                   "childPurchaseItems": [],
                   "quantity": 1
               }
           ],
           "quantity": 1
       }
   ],
   "details": {
       "totalAmount": 800.00,
       "taxAmount": 0.00,
       "changeAmount": 0.00,
       "taxes": [
           {
               "taxAmount": 0.00,
               "taxRate": {
                   "name": "Sales Tax",
                   "rate": 0.0000
               }
           }
       ]
   }
}
Voucher Endpoint
SALES TO BE RECOGNISED ON REPORTS  HOW TO CREATE A VOUCHER ON PHOREST SYSTEM

When you create a voucher with the API it’s like it is a manually added voucher so there won’t be a sale. It will actually show in the voucher history as manually added. There isn’t really a way to have it recognised for tax with the API, the salon would need to track manually added vouchers (or vouchers created by the API) separately.

You can’t create a purchase for a voucher with the API as the purchase endpoint http://developer.phorest.com/#!/Purchase/createPurchaseForBranch only works with appointments, products and courses.

At the moment the only way to have it registered as sales in Reports is to use our online voucher widget to register the sales on the report in Phorest. How do I sell Gift Cards/Vouchers online?

Q&A's

Transaction Id's

" In general, our app processes SQS message sent when purchase is made. Such message contains JSON payload including “transactionId”, e.g. "transactionId":”47208”. I’ve noticed, that this parameter isn’t unique. There are SQS messages sent for other purchases with the same “transactionId”. We were using this parameter before to filter out incoming SQS purchases originating from our API calls to Phorest, so that we don’t have duplicated orders. Is there any unique parameter we could rely on?

When making "post /api/business/{businessId}/branch/{branchId}/purchase” request, Phorest API returns the following data:

"purchaseId": "lLgBszR0rFFPhQe6J_UFcw",

"transactionNumber": 23157

As I understand “transactionNumber” is the same as “transactionId” from SQS message. Is there a way to fetch “purchaseId”, which seems like a unique value? It’s missing in SQS message and I cannot find any API method to get order / purchase details?"

 

The transactionId is unique for each branch. So there might be the same id’s if a business has two branches. In order to tell the purchases apart is by using the transactionId and the branchId.

Pagination

"We have a question regarding the operation of one of your api endpoints: 

https://developer.phorest.com/#!/StaffWorkTimeTables/getStaffWorkTimeTables.

The api is documented as paginated but during our tests we noticed that it return always all the values, without taking into consideration the pagination parameters provided in the query."

Examples:

With size=100 and page=1 

The totalPages value changes based on size, but everything else doesn’t. 

{
  {
  "_embedded": {
    “workTimeTables: [ … ]
  },
  "page": {
    "size": 247,
    "totalElements": 247,
    "totalPages": 3,
    "number": 0
  }
}

This instead without passing any pagination parameter: 

{
  "_embedded": {
    “workTimeTables: [ … ]
  },
  "page": {
    "size": 247,
    "totalElements": 247,
    "totalPages": 13,
    "number": 0
  }
}

We don't support pagination for https://developer.phorest.com/#!/StaffWorkTimeTables/getStaffWorkTimeTables endpoint and it always returns all records for a given date range.

Uploading Images

"Can we use the API to upload images by using the Booking endpoint?"

Currently we don't offer any way to add images via the API. A workaround might be for you to host your images somewhere of your choosing and include the link to the image into the appointment notes: https://developer.phorest.com/#!/Booking/appendNoteToBooking.

Sales Data

"Can we extract sales data so we can extract it into Xero using their API?"

 

The Phorest API can be used to extract the following jobs:

- TRANSACTIONS_CSs - containing all transaction data

- SUNDRIES_CSV - Sundries is just petty cash sales in the salon

- DATEV_CSV - Datev is for exporting financial data in Germany to import into accountancy software

- CLIENT_COURSES_CSV - Client course data

An example of using this functionality to extract Transaction data:

Include this in the body of the request (Enter your own dates):

{
"finishFilter": "2021-10-21",
"jobType": "TRANSACTIONS_CSV",
"startFilter": "2021-10-17"
}

This will return a JobId example response:

{
    "jobId": "-__UUYJak1Mh1Slv2uRN0A",
    "jobType": "TRANSACTIONS_CSV",
    "jobStatus": "SCHEDULED",
    "startFilter": "2021-10-17",
    "finishFilter": "2021-10-21"
}

Use that id in the following Get Request: https://platform.phorest.com/third-party-api-server/api/business/{==== BUSINESS_ID HERE ====}/branch/{=== BRANCH_ID HERE ====}/csvexportjob/{==== jobId Here ====}

The response provides a link to the csv data.

Wordpress

 " I am trying to find out whether we can manage online bookings on our website with Phorest. Is it integratable with WordPress? Or how does it usually work?"

You can integrate Phorest and add the Online Booking feature to your own website. Please see this link explaining How do I set up Online Booking on my website? Here you can find more info on How to embed the booking widget into a responsive website

Shopify

"How do I link Phorest up to Shopify"

Phorest does not support integration with  Shopify.  Phorest Online Store  syncs straight with your salon stock and your clients. You can find the Online Store FAQs by click here.

Xero

We have a potential accountant customer who currently has to manually enter Phorest sales invoice data into Xero. Can you please tell me whether it is possible to access sales invoice data via the Phorest API. Ideally we would want to use the Phorest API to extract sales invoice data and use the Xero API to automatically feed this data into Xero.

The Phorest API can be used to extract transaction data in the form of a csv file, which you could then manipulate into the Xero API

Use this endpoint: https://platform.phorest.com/third-party-api-server/api/business/{==== BUSINESS_ID HERE ====}/branch/{=== BRANCH_ID HERE ====}/csvexportjob

Include this in the body of the request (Enter your own dates):

{
"finishFilter": "2021-10-21",
"jobType": "TRANSACTIONS_CSV",
"startFilter": "2021-10-17"
}

This will return a JobId

Example Response

{
    "jobId": "-__UUYJak1Mh1Slv2uRN0A",
    "jobType": "TRANSACTIONS_CSV",
    "jobStatus": "SCHEDULED",
    "startFilter": "2021-10-17",
    "finishFilter": "2021-10-21"
}

Use that id in the following Get Request: https://platform.phorest.com/third-party-api-server/api/business/{==== BUSINESS_ID HERE ====}/branch/{=== BRANCH_ID HERE ====}/csvexportjob/{==== jobId Here ====}

The response provides a link to the csv data.

Was this article helpful?
0 out of 0 found this helpful