How to call on the API Endpoints

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.

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

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

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

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  

• 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"
}

• “ 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

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  

• 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
               }
           }
       ]
   }
}

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?