NAV Navbar
cURL

Introduction

Welcome to the Simple Salon API!

If you are looking to integrate your software with Simple Salon, please apply to be a Partner by contacting support@simplesalon.com.

If you are an existing company looking to grant access to a Simple Salon Partner, please see Initial Setup For Companies.

If you are a new company looking to signup for an account with Simple Salon, please visit our Sign Up page.

Initial Setup

For Partners

You will be provided with a Partner Token and a Signing Key when you are accepted into the Partner Program, as well as a Sandbox Partner Token, Signing Key and test Company ID.

When you connect with a company using Simple Salon, you will need to provide them with your Partner Token, and generate a Company Token for them.

Generating a Company Token

Example:

Partner Token: 'PartnerToken'
Company ID: '12345'
Signing Key: 'qwerty'

Sign: 'PartnerToken-12345'
using HMACSHA256 and your Signing Key to generate:
Company Token: 'd8d6cc9533d8ff1ce79764f770356e4e1055ac00d0ce53affe9e67dc2ed8e71e'

You will need the Company ID of the company to be able to generate a Company Token.

Combine your Partner Token and the Company ID into a string separated with a dash.
Sign the string with your Signing Key, using the HMACSHA256 algorithm and UTF8 encoding.
The result should be lowercase, alphanumeric characters only.

You must generate a Company Token for each company who uses your integration, and provide the company with only the Partner Token and Company Token.
Make sure that you are not including your Signing Key in your application code.

For Companies

You will need a Partner Token, and a Company Token from your integration partner. They will need your Company ID to generate the Company Token for you.

You will also need to enable the API in your Simple Salon settings (via your Account page, Actions menu, then API Settings), and enable access for your selected Partner on the same screen. If you don't see your Partner listed here, contact them to confirm they have signed up to be a Simple Salon Partner.

Sandbox Test Environment

A sandbox environment for testing your integration is available. You will have been assigned a test company when you were accepted into the Partner program.

You can login to the sandbox at: https://sandbox-app.simplesalon.com with your username, password, and test company ID.

The sandbox API is available at: https://sandbox-api.simplesalon.com. Remember to use the provided api_url returned with your token for requests made after initial log in.

Some functions in the sandbox have been disabled, such as SMS/Email and Online listings.

Version

Example Request:

curl "https://api.simplesalon.com/v1/version"

Example Response:

{
  "success": true,
  "build": "x.y.z"
  "version": "1.0"
}

Return the API version.

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
build string The internal build number.
version string The API version number (see Change Log).

Authentication

Once you have your Partner Token and Company Token, you can request a login token.

You can use the login token as authorisation to call the other API methods.

Login tokens expire - if your login token has expired, you can request a new one via the Refresh Login method.
If your login token has expired and has not been used in a long time, you may need to log in again to create a new login token.

Login

Example Request:

curl "https://api.simplesalon.com/v1/login"
  -H 'Content-Type: application/json' \
  -H 'User-Agent: MyWebsite 1.0' \
  -H 'X-Company-Token: d8d6cc9533d8ff1ce79764f770356e4e1055ac00d0ce53affe9e67dc2ed8e71e' \
  -H 'X-Partner-Token: PartnerToken' \
  -d '
  {
    "username":"myusername",
    "password":"mypassword",
    "company_id":12345
  }'

Example Response:

{
  "success": true,
  "api_url": "https://api1.simplesalon.com",
  "expiry": "2019-01-01T00:00:00+00:00",
  "token": "abcdef"
}

Request a login token using your standard username, password and Company ID combination that you use to log in to Simple Salon, as well as your Partner Token and Company Token.

If login is successful, you'll be provided with a login token. Any subsequent API requests need to include the login token in the request header: Authorization: Bearer abcdef, and be made to the api_url provided (plus version number and method name).

You may also receive a login notice message (such as a warning about upcoming maintenance, or a warning about your Simple Salon subscription expiring). These notices should be displayed directly to the user.

HTTP Request

POST /v1/login

HTTP Headers

Header Value
Content-Type Always application/json
User-Agent A description of the software and version you are using
X-Company-Token d8d6cc9533d8ff1ce79764f770356e4e1055ac00d0ce53affe9e67dc2ed8e71e
X-Partner-Token PartnerToken

Request Data

Parameter Type Description
username string required Your Simple Salon username
password string required Your Simple Salon password
company_id integer required Your Simple Salon Company ID

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
api_url string The API URL to use for all subsequent API calls, usually in the form https://apiN.simplesalon.com
token string The login token.
expiry string The expiry date of the login token, in UTC.
login_notice Message (optional) Only included if there is a warning to display at login.

Refresh Login

Example Request:

curl "https://apiN.simplesalon.com/v1/refresh"
  -H 'Content-Type: application/json' \
  -d '
  {
    "token":"abcdef"
  }'

Example Response:

{
  "success": true,
  "api_url": "https://api1.simplesalon.com",
  "expiry": "2019-01-01T00:00:00+00:00",
  "token": "ghijkl"
}

Use your existing login token to create a new login token, with a new expiry.
Your new login token must be used from then on - the existing login token is deauthorised and can no longer be used. You should also check if the api_url field has changed - you may be required to switch to using a different API URL for subsequent requests.

HTTP Request

POST /v1/refresh

Request Data

Parameter Type Description
token string required Your Simple Salon API login token

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
api_url string The API URL to use for all subsequent API calls, usually in the form https://apiN.simplesalon.com
token string The new login token.
expiry string The expiry date of the login token, in UTC.
login_notice Message Only returned if there is a warning to display at login.

Logout

Example Request:

curl "https://apiN.simplesalon.com/v1/logout"
  -H 'Content-Type: application/json' \
  -d '
  {
    "token":"abcdef"
  }'

Example Response:

{
  "success": true
}

Sign out of the API. Your login token is deauthorised and can no longer be used.

HTTP Request

POST /v1/logout

Request Data

Parameter Type Description
token string required Your Simple Salon API login token

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).

Clients

List

Example Request:

curl "https://apiN.simplesalon.com/v1/client/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {

        ...
    },
    "options":
    {
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "clients": [
        {
            "address_line1": "1 Example St",
            "address_postcode": "3000",
            "address_state_id": 3,
            "address_state": {
                "name": "VIC",
                "state_id": 3
            },
            "address_suburb": "Melbourne",
            "barcode": "8786745156874",
            "category_ids": [919],
            "categories": [
                {
                    "client_category_id": 919,
                    "name": "Loyalty Program"
                }
            ],
            "client_id": 1111,
            "comments": "",
            "company_id": 12345,
            "date_of_birth": "2017-10-18T00:00:00+11:00",
            "email": "",
            "email_promotions_enabled": false,
            "email_reminders_enabled": true,
            "firstname": "Joe",
            "gender": "Male",
            "lastname": "Citizen",
            "mobile": "",
            "referral_type_id": 29,
            "referral_type": {
                "name": "Digital Advertising",
                "referral_type_id": 29
            },
            "sms_promotions_enabled": false,
            "sms_reminders_enabled": true
        }
    ]
}

Get a list of clients.

HTTP Request

POST /v1/client/list

Request Data

Parameter Type Description
filters ClientFilter required The filters to apply to the client list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all clients (depending on the logged in user's permissions).

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
page_number integer The page number of these results
rows_per_page integer The number of rows per page
total_rows integer The total number of rows matching your filters. Only returned if options.return_total is true in the request.
clients Client[] The list of clients matching the filters and page options.

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/client/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_id": 1111
  }'

Example Response:

{
    "success": true,
    "client": 
    {
        "address_line1": "1 Example St",
        "address_postcode": "3000",
        "address_state_id": 3,
        "address_state": {
            "name": "VIC",
            "state_id": 3
        },
        "address_suburb": "Melbourne",
        "barcode": "8786745156874",
        "category_ids": [919],
        "categories": [
            {
                "client_category_id": 919,
                "name": "Loyalty Program"
            }
        ],
        "client_id": 1111,
        "comments": "",
        "company_id": 12345,
        "date_of_birth": "2017-10-18T00:00:00+11:00",
        "email": "",
        "email_promotions_enabled": false,
        "email_reminders_enabled": true,
        "firstname": "Joe",
        "gender": "Male",
        "lastname": "Citizen",
        "mobile": "",
        "referral_type_id": 29,
        "referral_type": {
            "name": "Digital Advertising",
            "referral_type_id": 29
        },
        "sms_promotions_enabled": false,
        "sms_reminders_enabled": true
    }
}

Gets a single client.

HTTP Request

POST /v1/client/get

Request Data

Parameter Type Description
client_id integer required The ID of the client to retrieve

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
client Client The client.

Add

Example Request:

curl "https://apiN.simplesalon.com/v1/client/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "firstname": "Joe",
    "lastname": "Citizen"
  }'

Example Response:

{
    "success": true,
    "client": 
    {
        "address_line1": "",
        "address_postcode": "",
        "address_state_id": 0,
        "address_suburb": "",
        "barcode": "",
        "category_ids": [],
        "client_id": 1112,
        "company_id": 12345,
        "email": "",
        "email_promotions_enabled": true,
        "email_reminders_enabled": true,
        "firstname": "Joe",
        "gender": "",
        "lastname": "Citizen",
        "mobile": "",
        "referral_type_id": 0,
        "sms_promotions_enabled": true,
        "sms_reminders_enabled": true
    }
}

Adds a new client.

Expanded fields (such as address_state) cannot be set directly - set their ID field (ie. address_state_id) instead.

HTTP Request

POST /v1/client/add

Request Data

Parameter Type Description
client Client required The client to add. Omitted or null fields are left as default values.
Field Notes for Add
client_id This field cannot be set.
company_id If the logged in user is a Dome user, this field must have a location company ID specified (you cannot add clients directly to the Dome company). For any other user, the company ID can be omitted and defaults to their own location (the only valid value).
category_ids If you are not allowing selecting of client categories in your integration, omit this field altogether and the default categories for a new client will be automatically added. Otherwise, your Add Client UI should initially have those default categories selected - use the add_to_new_clients filter with a Client Category List request to retrieve the list of default categories.
date_of_birth Timezone offset in this field is ignored. See Dates.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
client Client The added client.

Update

Example Request:

curl "https://apiN.simplesalon.com/v1/client/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_id": 56789,
    "firstname": "Joseph"
  }'

Example Response:

{
    "success": true,
    "client": 
    {
        "address_line1": "1 Example St",
        "address_postcode": "3000",
        "address_state_id": 3,
        "address_state": {
            "name": "VIC",
            "state_id": 3
        },
        "address_suburb": "Melbourne",
        "barcode": "8786745156874",
        "category_ids": [919],
        "categories": [
            {
                "client_category_id": 919,
                "name": "Loyalty Program"
            }
        ],
        "client_id": 1111,
        "comments": "",
        "company_id": 12345,
        "date_of_birth": "2017-10-18T00:00:00+11:00",
        "email": "",
        "email_promotions_enabled": false,
        "email_reminders_enabled": true,
        "firstname": "Joseph",
        "gender": "Male",
        "lastname": "Citizen",
        "mobile": "",
        "referral_type_id": 29,
        "referral_type": {
            "name": "Digital Advertising",
            "referral_type_id": 29
        },
        "sms_promotions_enabled": false,
        "sms_reminders_enabled": true
    }
}

Updates an existing client.

Expanded fields (such as address_state) cannot be updated directly - update their ID field (ie. address_state_id) instead.

HTTP Request

POST /v1/client/update

Request Data

Parameter Type Description
client Client required The client to update. Must specify client_id. Omitted or null fields are left unchanged.
Field Notes for Update
client_id This field cannot be changed.
company_id This field cannot be changed.
date_of_birth Timezone offset in this field is ignored. See Dates.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
client Client The updated client.

Delete

Example Request:

curl "https://apiN.simplesalon.com/v1/client/delete"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_id": 1112
  }'

Example Response:

{
    "success": true
}

Deletes a client.

HTTP Request

POST /v1/client/delete

Request Data

Parameter Type Description
client_id integer required The ID of the client to delete

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).

State List

Example Request:

curl "https://apiN.simplesalon.com/v1/state/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d ''

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "states": [
        {
            "name": "---",
            "state_id": 0
        },
        {
            "name": "ACT",
            "state_id": 1
        },
        {
            "name": "NSW",
            "state_id": 2
        },
        {
            "name": "VIC",
            "state_id": 3
        },
        {
            "name": "QLD",
            "state_id": 4
        },
        {
            "name": "NT",
            "state_id": 5
        },
        {
            "name": "SA",
            "state_id": 6
        },
        {
            "name": "TAS",
            "state_id": 7
        },
        {
            "name": "WA",
            "state_id": 8
        },
        {
            "name": "Other",
            "state_id": 75
        }
    ]
}

Get a list of geographical states.

With no filter parameters, it will return the states contained in the country of the logged in user's company.

HTTP Request

POST /v1/state/list

Request Data

Parameter Type Description
filters StateFilter The filters to apply to the state list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all states.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
states State[] The list of states matching the filters.

Referral Type List

Example Request:

curl "https://apiN.simplesalon.com/v1/referral_type/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d ''

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "referral_types": [
        {
            "name": "Friend",
            "referral_type_id": 1
        },
        {
            "name": "Email",
            "referral_type_id": 2
        },
        {
            "name": "SMS",
            "referral_type_id": 3
        },
        ...
    ]
}

Get a list of client referral types.

HTTP Request

POST /v1/referral_type/list

Request Data

Parameter Type Description
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all referral types.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
referral_types ReferralType[] The list of referral types.

Client Category List

Example Request:

curl "https://apiN.simplesalon.com/v1/client_category/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters": {
        "add_to_new_clients":true
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "categories": [
        {
            "add_to_new_clients": true,
            "client_category_id": 1,
            "name": "Loyalty Program"
        },
        ...
    ]
}

Get a list of client categories.

HTTP Request

POST /v1/client_category/list

Request Data

Parameter Type Description
filters ClientCategoryFilter The filters to apply to the client category list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all client categories.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
categories ClientCategory[] The list of client categories for the company.

Models

ClientFilter

Parameter Type Description
barcode string The barcode of the client to retrieve.
client_category_id integer The ID of the client category to filter clients by.
company_id integer The company ID to retrieve clients for. If omitted, defaults to the logged in user's company ID. For a Client List call, you can specify 0 to retrieve all clients within the entire Dome (from other companies who are sharing clients with the logged in user's company).
firstname string The firstname to search by - partial match, eg. if you send Jo, you will get results starting with Jo: Jo, Joe and Joan
email string The email address to search by - exact match only.
email_promotions_enabled boolean true for clients who have Email Promotion messages enabled, false for clients who have Email Promotion messages disabled. If omitted, returns both.
email_reminders_enabled boolean true for clients who have Email Reminder messages enabled, false for clients who have Email Reminder messages disabled. If omitted, returns both.
gender string The gender to filter clients by. Options are Male, Female, or an empty string (to return clients who don't have a gender set).
lastname string The lastname to search by - partial match, eg. if you send Jo, you will get results starting with Jo: Jones, Johnson and Jolly
operator_id integer The ID of the operator to filter clients by (their preferred operator).
phone string The phone number to search by - partial match, eg. if you send 1234, you will get results starting with 1234: 1234, 123456 and 12345678. Searches both Telephone and Mobile fields for matches.
referral_type_id integer The ID of the referral type to filter clients by.
search_all_dome bool If you are in a dome, setting this to true will search for clients across all companies (who are sharing clients with the logged in user's company). If omitted, defaults to false to search only the user's company.
sms_promotions_enabled boolean true for clients who have SMS Promotion messages enabled, false for clients who have SMS Promotion messages disabled. If omitted, returns both.
sms_reminders_enabled boolean true for clients who have SMS Reminder messages enabled, false for clients who have SMS Reminder messages disabled. If omitted, returns both.

Client

Parameter Type Description
client_id integer The ID of the client.
account_balance decimal The client's account balance. This field is read-only.
address_line1 string The street address of the client's postal address.
address_suburb string The suburb of the client's postal address.
address_postcode string The postcode/zipcode of the client's postal address.
address_state_id integer The geographical state ID of the client's postal address.
address_state State Expanded field of address_state_id. The geographical state of the client's postal address.
barcode string The barcode number of the client.
category_ids integer[] The list of client category IDs this client belongs to.
categories ClientCategory[] Expanded field of category_ids. The list of client categories this client belongs to.
comments string The client comments.
company_id integer The company ID of the client. This field is read-only.
date_of_birth string The date of birth of the client. Time and timezone offset in this field are ignored. See Dates.
email string The email address of the client.
email_promotions_enabled boolean Whether the client wishes to receive promotional messages via email.
email_reminders_enabled boolean Whether the client wishes to receive reminder messages via email.
firstname string The firstname of the client.
gender string The gender of the client.
instagram string The client's Instagram username.
lastname string The lastname/surname of the client.
loyalty_member boolean Whether the client is a member of the Loyalty Program client category. This field is read-only - add or remove the client from the Loyalty Program client category to modify it.
loyalty_points integer The number of loyalty points the client currently has.
mobile string The mobile/cell number of the client.
phone string The telephone number of the client.
preferred_operator_id integer The ID of the client's preferred operator.
referral_type_id integer The referral type ID of the client.
referral_type ReferralType Expanded field of referral_type_id. The referral type of the client.
referred_by_client_id integer The ID of the client who referred this client.
sms_promotions_enabled boolean Whether the client wishes to receive promotional messages via SMS.
sms_reminders_enabled boolean Whether the client wishes to receive reminder messages via SMS.
twitter string The client's Twitter username.

Client Category

Parameter Type Description
client_category_id integer The ID of the client category.
name string The name of the client category.
add_to_new_clients boolean true if this category is automatically added to new clients, false if not.

ClientCategoryFilter

Parameter Type Description
add_to_new_clients boolean If set, only returns client categories matching the filter value. If omitted, all categories are returned.

Referral Type

Parameter Type Description
referral_type_id integer The ID of the referral type.
name string The name of the referral type.

StateFilter

Parameter Type Description
country_id integer The ID of the country to return states for. If omitted, defaults to the country of the logged in user's company.
include_other boolean If true, includes the Other state option. If omitted, defaults to false, which excludes the Other state.

State

Parameter Type Description
state_id integer The ID of the geographical state.
name string The name of the geographical state.

Special Values

Walk In Client

A client_id value of -1 indicates the Walk In client. This is used to record a transaction for a client that you have not created a client record for.

An example of a Walk In sale would be if someone has walked in off the street just to buy a product. In this case you would not normally ask for their name and personal details - just record the sale under the Walk In client.

The Walk In client cannot be used in a sale with any other clients, cannot purchase packages or memberships, cannot add account value, cannot be booked into a future service and cannot load or save sales.

Company Use Client

A client_id value of -2 indicates the Company Use client. When an item is used within the company, it can be marked as sold to the Company Use client to keep track of how much stock is available for sale. This sale is not included in the usual sales reporting figures.

An example of a Company Use item would be a bottle of hairspray used by the operator at the end of each haircut. The client does not pay for this bottle of hairspray, and it is used again for the next client.

The Company Use client cannot be used in a sale with any other clients, cannot purchase packages or memberships, cannot add account value, cannot be booked into a future service and cannot load or save sales.

Operators

List

Example Request:

curl "https://apiN.simplesalon.com/v1/operator/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        "show_on_appt_page": true,
        ...
    },
    "options":
    {
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "operators": [
        {
            "company_id": 12345,
            "display_name": "Ash",
            "firstname": "Ashley",
            "lastname": "Smith",
            "level": {
                "level_id": 100,
                "name": "Apprentice"
            },
            "level_id": 100,
            "operator_id": 2222,
            "order_num": 0
        },
        ...
    ]
}

Get a list of operators.

HTTP Request

POST /v1/operator/list

Request Data

Parameter Type Description
filters OperatorFilter required The filters to apply to the operator list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all operators.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
operators Operator[] The list of operators matching the filters.

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/operator/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "operator_id": 2222
  }'

Example Response:

{
    "success": true,
    "operator": 
    {
        "company_id": 12345,
        "display_name": "Ash",
        "firstname": "Ashley",
        "lastname": "Smith",
        "level": {
            "level_id": 100,
            "name": "Apprentice"
        },
        "level_id": 100,
        "operator_id": 2222,
        "order_num": 0
    }
}

Gets a single operator.

HTTP Request

POST /v1/operator/get

Request Data

Parameter Type Description
operator_id integer required The ID of the operator to retrieve

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
operator Operator The operator.

Add

Example Request:

curl "https://apiN.simplesalon.com/v1/operator/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "operator": 
    {
        "operator_id": 2222,
        "display_name": "Lee"
    }
  }'

Example Response:

{
    "success": true,
    "operator": 
    {
        "company_id": 12345,
        "display_name": "Lee",
        "firstname": "",
        "lastname": "",
        "level_id": 0,
        "operator_id": 2223,
        "order_num": 0
    }
}

Adds a new operator.

HTTP Request

POST /v1/operator/add

Request Data

Parameter Type Description
operator Operator required The operator to add.
Field Notes for Add
operator_id This field must be omitted.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
operator Operator The new operator.

Update

Example Request:

curl "https://apiN.simplesalon.com/v1/operator/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "operator": 
    {
        "operator_id": 2222,
        "display_name": "Ash S"
    }
  }'

Example Response:

{
    "success": true,
    "operator": 
    {
        "company_id": 12345,
        "display_name": "Ash S",
        "firstname": "Ashley",
        "lastname": "Smith",
        "level": {
            "level_id": 100,
            "name": "Apprentice"
        },
        "level_id": 100,
        "operator_id": 2222,
        "order_num": 0
    }
}

Updates an operator.

HTTP Request

POST /v1/operator/update

Request Data

Parameter Type Description
operator Operator required The operator to update. Must specify operator_id. Omitted or null fields are left unchanged.
update_in_child_locations OperatorChildField If you are updating a Dome operator, you can optionally specify each field to overwrite on the child operators as well. If omitted, these fields will not be copied down. Fields not included in this list are always copied down, as they cannot be separately edited by the child location.
Field Notes for Update
operator_id This field cannot be changed.
company_id This field cannot be changed.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
operator Operator The updated operator.

Delete

Example Request:

curl "https://apiN.simplesalon.com/v1/operator/delete"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "operator_id": 2223
  }'

Example Response:

{
    "success": true
}

Deletes an operator.

HTTP Request

POST /v1/operator/delete

Request Data

Parameter Type Description
operator_id integer required The ID of the operator to delete

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).

Operator Level List

Example Request:

curl "https://apiN.simplesalon.com/v1/operator_level/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d ''

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "operator_levels": [
        {
            "name": "Apprentice",
            "level_id": 100
        },
        {
            "name": "Master",
            "level_id": 200
        }
    ]
}

Get a list of operator levels.

HTTP Request

POST /v1/operator_level/list

Request Data

Parameter Type Description
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all operator levels.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
operator_levels OperatorLevel[] The list of operator levels matching the filters.

Models

Operator

Parameter Type Description
operator_id integer The ID of the operator.
address_line1 string The street address of the operator's postal address.
address_suburb string The suburb of the operator's postal address.
address_postcode string The postcode/zipcode of the operator's postal address.
address_state_id integer The geographical state ID of the operator's postal address.
address_state State Expanded field of address_state_id. The geographical state of the operator's postal address.
commission_packages decimal The percentage commission for sale of packages.
commission_products_profit decimal The percentage commission (on net profit) for sale of products.
commission_products_revenue decimal The percentage commission for sale of products.
commission_services decimal The percentage commission for sale of services.
commission_vouchers decimal The percentage commission for sale of vouchers.
company_id integer The company ID of the operator.
date_of_birth string The date of birth of the operator. Time and timezone offset in this field are ignored. See Dates.
display_name string The display name of the operator.
dome_operator_id integer The ID of the operator in the Dome.
email string The email address of the operator.
email_appointment_updates_enabled boolean Whether the operator wishes to receive appointment update messages via email.
firstname string The firstname of the operator.
gender string The gender of the operator.
kpi_avgclientspendperday decimal The KPI rate for Average Client Spend per Day.
kpi_clientsperday decimal The KPI rate for Clients Per Day.
kpi_rebookrate decimal The percentage KPI rate for Rebooking.
kpi_retailsales decimal The percentage KPI rate for Retail Sales.
kpi_wagesvssales decimal The percentage KPI rate for Wages vs Sales.
lastname string The lastname/surname of the operator.
level_id integer The ID of the operator's level.
level Level Expanded field of level_id. The operator's level.
mobile string The mobile/cell number of the operator.
order_num integer The display order of the operator.
phone string The telephone number of the operator.
pin int The quick login pin of the operator.
role_id integer The ID of the operator's role.
show_on_appointment_page boolean If true, this operator will have a column shown on the appointment page.
sms_appointment_updates_enabled boolean Whether the operator wishes to receive appointment update messages via SMS.
welcome_page string The page to load when this operator first logs in. Valid values are an empty string (to use the company's welcome page setting), appointments, pos, reporting or resources.

Operator Level

Parameter Type Description
level_id integer The ID of the operator level.
name string The name of the operator level.

OperatorFilter

Parameter Type Description
company_id integer The company ID to retrieve operators for. If omitted, defaults to the logged in user's company ID.
is_system boolean true for the System Operator, false for excluding the System Operator. If omitted, returns both.
show_on_appt_page boolean true for operators visible on the appointment page, false for operators not shown directly on the appointments page. If omitted, returns both.

OperatorChildField

If any fields are omitted, they will default to false.

Parameter Type Description
display_name boolean If true, the Dome operator's display name will be copied down to each child location operator.
level_id boolean If true, the Dome operator's level ID will be copied down to each child location operator.
order_num boolean If true, the Dome operator's order will be copied down to each child location operator.

Special Values

System Operator

An operator_id value of -1 indicates the System Operator - ie. an operator was not assigned.

System Operator reasons can include (but are not limited to):

Services

List

Example Request:

curl "https://apiN.simplesalon.com/v1/service/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        "category_id": 0,
        ...
    },
    "options":
    {
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "services": [
        {
            "barcode": "",
            "category_id": 0,
            "name": "Haircut",
            "price": 10.00,
            "service_id": 3333
        },
        ...
    ]
}

Get a list of services.

HTTP Request

POST /v1/service/list

Request Data

Parameter Type Description
filters ServiceFilter required The filters to apply to the service list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all services in a specific category.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
services Service[] The list of services matching the filters.

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/service/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "service_id": 3333
  }'

Example Response:

{
    "success": true,
    "service": 
    {
        "barcode": "",
        "category_id": 0,
        "name": "Haircut",
        "price": 10.00,
        "service_id": 3333
    }
}

Gets a single service.

HTTP Request

POST /v1/service/get

Request Data

Parameter Type Description
service_id integer required The ID of the service to retrieve

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
service Service The service.

Add

Example Request:

curl "https://apiN.simplesalon.com/v1/service/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "service": 
    {
        "name": "Beard Trim",
        "price": 12.50
    }
  }'

Example Response:

{
    "success": true,
    "service": 
    {
        "barcode": "",
        "category_id": 0,
        "name": "Beard Trim",
        "price": 12.50,
        "service_id": 3334
    }
}

Adds a new service.

HTTP Request

POST /v1/service/add

Request Data

Parameter Type Description
service Service required The service to add.
Field Notes for Add
service_id This field must be omitted.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
service Service The new service.

Update

Example Request:

curl "https://apiN.simplesalon.com/v1/service/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "service": 
    {
        "service_id": 3333,
        "name": "Kids Haircut"
    }
  }'

Example Response:

{
    "success": true,
    "service": 
    {
        "barcode": "",
        "category_id": 0,
        "name": "Kids Haircut",
        "price": 10.00,
        "service_id": 3333
    }
}

Updates a service.

HTTP Request

POST /v1/service/update

Request Data

Parameter Type Description
service Service required The service to update. Must specify service_id. Omitted or null fields are left unchanged.
update_in_child_locations ServiceChildField If you are updating a Dome service, you can optionally specify each field to overwrite on the child services as well. If omitted, these fields will not be copied down. Fields not included in this list are always copied down, as they cannot be separately edited by the child location.
apply_new_price_for_future_appts boolean If you've updated the price, set this to true to apply the new price to any existing bookings in the future. Setting to false will leave those future appointments at their existing price, and any new appointments booked in from now on will have the new pricing. If omitted, defaults to false.
Field Notes for Update
service_id This field cannot be changed.
company_id This field cannot be changed.
group_service This field cannot be changed.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
service Service The updated service.

Delete

Example Request:

curl "https://apiN.simplesalon.com/v1/service/delete"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "service_id": 3334
  }'

Example Response:

{
    "success": true
}

Deletes a service.

HTTP Request

POST /v1/service/delete

Request Data

Parameter Type Description
service_id integer required The ID of the service to delete

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).

Service Children List

Example Request:

curl "https://apiN.simplesalon.com/v1/service/children/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "service_id":3333
  }'

Example Response:

{
    "success": true,
    "services": [
        {
            "barcode": "",
            "category_id": 0,
            "name": "Haircut",
            "price": 10.00,
            "service_id": 3334
        },
        {
            "barcode": "",
            "category_id": 0,
            "name": "Blow Dry",
            "price": 10.00,
            "service_id": 3335
        }
    ]
}

Returns the child services included in the requested Group Service, plus the order they should be booked (if the group service has override_duration: false).

HTTP Request

POST /v1/service/children/list

Request Data

Parameter Type Description
service_id integer required The ID of the group service.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
services Service[] The child services part of this group service, with order field filled out if the group service has override_duration: false.

Category List

Example Request:

curl "https://apiN.simplesalon.com/v1/category/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "categories": [
        {
            "category_id": 0,
            "name": "No Category"
        },
        ...
    ]
}

Get a list of service categories.

HTTP Request

POST /v1/category/list

Request Data

Parameter Type Description
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all categories.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
categories Category[] The list of categories for the company.

Special Types

Group

A group service is a pre-determined set of child services, which are then sold/booked together. The group service contains the child services, and can optionally override either the total price of all included services (override_price), or the total duration of all the included services (override_duration), or both.
For example, a 'Haircut and Blow Dry' group service would contain the 'Haircut' service followed by the 'Blow Dry' service.

Multi

A service_id value of -1 indicates the Multi service - this is when a normal appointment has an extra appointment added on to it, without extending the time. This creates a group parent (the Multi service, with override_duration: true), and changes the existing appointment and new appointment to be children of the new Multi service appointment.

Models

Service

Parameter Type Description
service_id integer The ID of the service.
allow_multiple_clients boolean If true, this service is a Class, that can accept multiple clients in a single timeslot. If false, there can be only one client.
barcode string The barcode of the service.
category_id integer The category ID.
category Category Expanded field of category_id. The service's category.
company_id integer The company ID of the service.
display_colour string The colour to display the service on the appointment page. Must be in six-character Hex RRGGBB format, eg. FFFFFF for White, 000000 for Black, FF0000 for Red.
dome_service_id integer The ID of the service in the Dome.
duration integer The length of time for the service, in minutes. Must non-zero, and a multiple of the company's appointment interval.
group_service boolean If true, this service is a group service, which is a combination of other services. This must be set when creating the service. See Group Services.
loyalty_points_earned integer The amount of loyalty points earned from purchasing this service.
loyalty_points_to_redeem integer The amount of loyalty points needed to redeem this service.
maximum_clients integer When allow_multiple_clients is true, you can use this field to restrict the number of clients allowed in this Class. Leave at 0 or null to allow an unlimited number of clients.
name string The name of the service.
online_booking_name string The name of the service as displayed on your online booking website.
override_duration boolean When group_service is true, setting this field to true allows you to set a custom duration for the group service. If false, the duration will be the total of all included service durations, plus any in-between processing durations.
override_price boolean When group_service is true, setting this field to true allows you to set a custom price for the group service. If false, the price will be the total of all included service prices.
order int When requesting the child services of a group service, if the group service's override_duration: false, then this field will indicate the order that this child service should be performed, relative to the other child service order fields. Only used in the Service Children List API call.
price decimal The price of the service.
processing_duration integer The length of time for service processing, in minutes. Eg. the time it takes for a client's hair to dry - the operator can perform services on other clients during this time, but subsequent services for this client must wait until the processing time is finished. Must a multiple of the company's appointment interval.
requires_resource boolean If true, this service requires a resource room to be available. You must then set the resources rooms which can be used for this service (otherwise attempting to book this service will fail, as it cannot assign a resource room).
tax_free boolean If true, this service does not have tax applied.

Category

Parameter Type Description
category_id integer The ID of the category.
name string The name of the category.

ServiceFilter

Parameter Type Description
barcode string The barcode to search for - must be an exact match. If omitted, returns all.
company_id integer The company ID to retrieve services for. If omitted, defaults to the logged in user's company ID.
category_id integer The category ID to filter by. If omitted, returns all.
dome_service_id integer The dome service ID to filter by. This will return the child location service, if it exists in the specified company. If omitted, returns all.
loyalty_points_to_redeem integer Returns services that can be redeemed with this amount of loyalty points. If omitted, returns all.
operator_id integer Specifying the operator ID will restrict the results to only the services that this operator can perform. If omitted, returns all.

ServiceChildField

If any fields are omitted, they will default to false.

Parameter Type Description
price boolean If true, the Dome service's price will be copied down to each child location service.

Appointments

List

Example Request:

curl "https://apiN.simplesalon.com/v1/appointment/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        "time_start":"2019-01-01T00:00:00+00:00",
        "time_end":"2019-01-02T00:00:00+00:00",
        ...
    },
    "options":
    {
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "total_rows": 1,
    "appointments": [
        {
            "appointment_id": 56789,
            "client_id": 1111,
            "company_id": 12345,
            "duration": 30,
            "operator_id": 2222,
            "resource_id": 0,
            "service_id": 3333,
            "time_end": "2019-01-01T11:15:00+11:00",
            "time_start": "2019-01-01T10:45:00+11:00"
        }
    ]
}

Get a list of appointments between a date range.

Note: Results are normally restricted by the ListOptions rows_per_page limit.
However for the following special cases, you can set rows_per_page: -1 to return all appointments at once:

HTTP Request

POST /v1/appointment/list

Request Data

Parameter Type Description
filters AppointmentFilter required The filters to apply to the appointment list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all appointments for a single day only.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
page_number integer The page number of these results
rows_per_page integer The number of rows per page
total_rows integer The total number of rows matching your filters. Only returned if options.return_total is true in the request.
appointments Appointment[] The list of appointments matching the filters and page options.

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/appointment/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "appointment_id": 56789
  }'

Example Response:

{
    "success": true,
    "appointment": 
    {
        "appointment_id": 56789,
        "client_id": 1111,
        "company_id": 12345,
        "duration": 30,
        "operator_id": 2222,
        "resource_id": 0,
        "service_id": 3333,
        "time_end": "2019-01-01T11:15:00+11:00",
        "time_start": "2019-01-01T10:45:00+11:00"
    }
}

Gets a single appointment.

HTTP Request

POST /v1/appointment/get

Request Data

Parameter Type Description
appointment_id integer required The ID of the appointment to retrieve

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
appointment Appointment The appointment.

Example Request:

curl "https://apiN.simplesalon.com/v1/appointment/add/search"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "appointments":  [
        {
            "operator_id": 2222,
            "service_id": 3333
        }
    ],
    "time_start": "2019-01-01T11:00:00+11:00"
  }'

Example Response:

{
    "success": true,
    "options": [
        {
            "appointments": [
                {
                    "company_id": 12345,
                    "duration": 15,
                    "operator_id": 2222,
                    "service_id": 3333,
                    "time_end": "2019-01-01T11:15:00+11:00",
                    "time_start": "2019-01-01T11:00:00+11:00"
                }
            ]
        },
        {
            "appointments": [
                {
                    "company_id": 12345,
                    "duration": 15,
                    "operator_id": 2222,
                    "service_id": 3333,
                    "time_end": "2019-01-01T11:30:00+11:00",
                    "time_start": "2019-01-01T11:15:00+11:00"
                }
            ]
        }
    ]
}

Given a set of appointments, finds options of available timeslots for those appointments to be booked in. Searches up to a maximum of 7 days from the time_start. Returns a maximum of 7 options per company - to see other options, call again with time_start adjusted accordingly.
If you search for an appointment with a Group Service, do not include the child appointments - both the group parent appointment and group child appointments will be returned in the options list, linked by pos_id and parent_pos_id.

HTTP Request

POST /v1/appointment/add/search

Request Data

Parameter Type Description
appointments Appointment[] required The appointments to search for a timeslot for. Must specify service_id, can optionally specify operator_id (see Notes for Add Search below). All other fields are ignored.
company_id integer If omitted, defaults to the logged in user's company ID. Selecting the Dome company ID will find the first available appointment, and then returns up to 7 options from each child company for that day.
direction string The direction to search from time_start. Valid values are: forward (appointments on or after time_start) and middle (appointments both before and after time_start). If omitted, defaults to forward.
time_start string The time to start the search from. If omitted, defaults to the next hour in the user's current time. Timezone offset in this field is ignored. See Dates.
Field Notes for Add Search
operator_id If omitted, available timeslots for this service will be returned for the first available operator.
pos_id If searching for a Group Service, you can specify your own pos_id for the group service parent, and the option results will have pos_id reflected on the group parent, and parent_pos_id reflected on its group children. If omitted, a random ID will be generated for the group service parent.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
appointments Appointment[] The appointment options. Only company_id, operator_id, service_id, time_start, time_end and duration fields will be set.

Add

Example Request:

curl "https://apiN.simplesalon.com/v1/appointment/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "appointments":  [
        {
            "client_id": 1111,
            "duration": 15,
            "operator_id": 2222,
            "service_id": 3333,
            "time_start": "2019-01-01T11:00:00+11:00"
        }
    ],
    "send_confirmation": true
  }'

Example Response:

{
    "success": true,
    "appointments": [
        {
            "appointment_id": 56789,
            "client_id": 1111,
            "company_id": 12345,
            "duration": 15,
            "operator_id": 2222,
            "resource_id": 0,
            "service_id": 3333,
            "time_end": "2019-01-01T11:15:00+11:00",
            "time_start": "2019-01-01T11:00:00+11:00"
        }
    ]
}

Adds new appointments. There must be space available in the appointment page for the appointments to fit, unless the new appointment is a child service (either parent_appointment_id is set, or parent_pos_id is set and the new parent appointment's service is a group service with override_duration: true).
If you add an appointment with a Group Service, you must also include all the child appointments (see Service Children List for retrieving the list of required services for a group service).

When adding to an existing appointment using parent_appointment_id, the existing appointment must be visible on the appointment page, and must have the same client_id.

HTTP Request

POST /v1/appointment/add

Request Data

Parameter Type Description
appointments Appointment[] required The appointments to add. Must specify client_id, duration, operator_id, service_id, time_start.
send_confirmation boolean If true, the client will receive a confirmation SMS and/or Email with their appointment time. If omitted, defaults to false.
Field Notes for Add
company_id If omitted, defaults to the logged in user's company ID. Dome users must specify a child location.
operator_id This field is required. However if the resource_id field is set, the operator_id can optionally be set to the System Operator.
parent_appointment_id If you are adding a new child appointment to an existing appointment, send the existing appointment's appointment_id. The new appointment must have the same client_id as the existing appointment.
parent_pos_id Required if the appointment is a child of a group service added in the same call. Set the pos_id to a unique value on the new group parent, and set the parent_pos_id on the new child appointments to match the group parent's pos_id.
pos_id Required if the appointment's service is a group service. If you are adding a new group appointment with new child appointments, set the pos_id to a unique value on the new group parent, and set the parent_pos_id on the new child appointments to match the group parent's pos_id.
resource_id A resource will be assigned automatically if the service requires a Resource and this field is omitted.
time_start Timezone offset in this field is ignored. See Dates.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
appointments Appointment[] The added appointments.

Update

Example Request:

curl "https://apiN.simplesalon.com/v1/appointment/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "appointment": 
    {
        "appointment_id": 56789,
        "duration": 15,
        "time_start": "2019-01-01T11:00:00+11:00"
    }
  }'

Example Response:

{
    "success": true,
    "appointment": 
    {
        "appointment_id": 56789,
        "client_id": 1111,
        "company_id": 12345,
        "duration": 15,
        "operator_id": 2222,
        "resource_id": 0,
        "service_id": 3333,
        "time_end": "2019-01-01T11:15:00+11:00",
        "time_start": "2019-01-01T11:00:00+11:00"
    }
}

Updates an existing appointment.

HTTP Request

POST /v1/appointment/update

Request Data

Parameter Type Description
appointment Appointment required The appointment to update. Must specify appointment_id. Omitted or null fields are left unchanged.
Field Notes for Update
client_id This field cannot be changed.
company_id This field can only be changed in a Dome. If changed, service_id, operator_id and resource_id must also be updated to valid values matching the new company.
resource_id You can clear the existing resource by setting this field to 0. If a resource is required for this service, a new one will be automatically assigned (or the update call will fail if no matching resources are available).
time_end This field is ignored - update duration to change the end time.
time_start Timezone offset in this field is ignored. See Dates.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
appointment Appointment The updated appointment.

Delete

Example Request:

curl "https://apiN.simplesalon.com/v1/appointment/delete"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "appointment_id": 56789
  }'

Example Response:

{
    "success": true
}

Deletes an appointment.

HTTP Request

POST /v1/appointment/delete

Request Data

Parameter Type Description
appointment_id integer required The ID of the appointment to delete

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).

Models

AppointmentFilter

Parameter Type Description
time_start string required The date to retrieve appointments from (inclusive). Timezone offset in this field is ignored. See Dates.
time_end string required The date to retrieve appointments to (exclusive). Timezone offset in this field is ignored. See Dates.
claimed boolean false for appointments purchased as part of a package, that have not yet been locked in, true for all other appointments. If omitted, returns both. Requires client_id to also be set.
client_id integer The client ID to retrieve appointments for.
company_id integer The company ID to retrieve appointments for. If omitted, defaults to the logged in user's company ID. For an Appointment List call, you can specify 0 to retrieve all appointments within a Dome.
double_booked boolean true for appointments that are double booked, false for appointments that are not. If omitted, returns both.
operator_id integer The operator ID to retrieve appointments for.
parent_appointment_id integer For retrieving a list of child appointments for a group service or multi service
preset string Valid values are:
- pos_future for returning future unpaid appointments for a client at POS (client_id must also be specified)
resource_id integer The resource ID to retrieve appointments for.
show_on_appt_page boolean true for appointments visible on the appointment page, false for appointments not shown directly on the appointments page. If omitted, returns both.

Appointment

Parameter Type Description
appointment_id integer The ID of the appointment.
can_redeem_via_loyalty_points boolean If true, this appointment could be redeemed by spending the client's loyalty points. This field is only included when relevant (ie. with a POS-related API call).
can_redeem_via_package boolean If true, this appointment could be redeemed by claiming one of the client's previously purchased (and as yet unclaimed) package items. This field is only included when relevant (ie. with a POS-related API call).
claimed boolean false for appointments purchased as part of a package, that have not yet been locked in, true for all other appointments.
client_id integer The client ID of the appointments.
comments string The comments of the appointment.
company_id integer The company ID of the appointment.
discount_type_id integer The discount type ID of the appointment, or 0 for none.
duration integer The duration of the appointment, in minutes.
loyalty_points_to_redeem integer The amount of loyalty points the client needs to spend to claim this appointment. Omitted if can_redeem_via_loyalty_points is false or omitted.
operator_id integer The operator ID of the appointment.
parent boolean true for a group service or multi service appointment parent, false for all other appointments.
parent_appointment_id integer The ID of the appointment's parent appointment (for an appointment part of a group).
parent_pos_id string Your unique identifier for this appointment's unsaved group parent. Only used in the Add Transaction, Add Appointments and Add Appointments Search API calls.
pos_id string Your unique identifier for an unsaved appointment. Only used in the Add Transaction, Add Appointments and Add Appointments Search API calls. Must be unique within each API call - you cannot have two items with the same pos_id on a single call to the API.
pos_original_price decimal The original or standard price of the appointment, before any discount is applied. Only set when using POS or Transaction API calls.
price decimal The price of the appointment.
resource_id integer The resource ID of the appointment, or 0 for none.
service_id integer The service ID of the appointment.
service Service A minimal Service object, to provide the service name and category name.
task boolean If true, this appointment is a task for the operator, and is not a service for a client.
time_end string The end time of appointment.
time_start string The start time of the appointment.
transaction_id integer The transaction ID of the appointment, or 0 for none.

Opening Hours

Summary

Calculating the exact opening hours for a specific operator on a specific day involves several pieces of information:
First, check the setting for advanced_rostering.

If advanced_rostering is true:

  1. Request the location's opening hours for the day (Opening Hours - List) - don't specify an operator_id.
    1. If the opening hours for the day are flagged as closed, then this day is completely closed and you don't need to continue with the other steps.
  2. Timeslots outside of the opening hours' time_start and time_end are always closed.
  3. Request the advanced roster for the operator and day (Rosters - List)
  4. For any timeslots between the opening hours' time_start and time_end that are covered by a roster:
    1. If the company_id matches yours, use the allow_bookings field on the roster's Roster Type to determine if the timeslot is open.
    2. If the company_id doesn't match yours (ie. in a Dome - rosters for other locations will be returned) then this timeslot is closed for all other companies, including your company.
  5. For any timeslots between the opening hours' time_start and time_end that are not covered by a roster, check the setting auto_roster_off: if it's on, then the timeslot defaults to closed, if it's off, then the timeslot defaults to open.

If advanced_rostering is false:

  1. Request the opening hours for the operator and day (Opening Hours - List) - specify an operator_id.
    1. If the opening hours for the day are flagged as closed, then this day is completely closed and you don't need to continue with the other steps.
  2. Timeslots in between the opening hours' time_start and time_end are open, and timeslots outside of time_start and time_end are closed.

List

Example Request:

curl "https://apiN.simplesalon.com/v1/hours/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        "time_start":"2019-01-01T00:00:00+00:00",
        "time_end":"2019-01-02T00:00:00+00:00",
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 1,
    "total_rows": 1,
    "hours": [
        {
            "hours_id": 998776,
            "company_id": 12345,
            "closed": false,
            "day": "tuesday",
            "duration": 30,
            "operator_id": 2222,
            "time_end": "2019-01-01T11:15:00+11:00",
            "time_start": "2019-01-01T10:45:00+11:00"
        }
    ]
}

Get a list of opening hours.
Currently returns all results (no paging).

HTTP Request

POST /v1/hours/list

Request Data

Parameter Type Description
filters OpeningHoursFilter required The filters to apply to the opening hours list

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
page_number integer The page number of these results
rows_per_page integer The number of rows per page
total_rows integer The total number of rows matching your filters. Only returned if options.return_total is true in the request.
hours Opening Hours[] The list of opening hours matching the filters and page options.

Models

Opening Hours Filter

Parameter Type Description
time_start string The date to retrieve hours from (inclusive). Time portion of this field is ignored. Timezone offset in this field is ignored. See Dates. If omitted (along with time_end), the standard opening hours for a week will be returned.
time_end string The date to retrieve hours to (exclusive). Time portion of this field is ignored. Timezone offset in this field is ignored. See Dates. If omitted (along with time_start), the standard opening hours for a week will be returned.
company_id integer The company ID to retrieve hours for. If omitted, defaults to the logged in user's company ID.
operator_id integer The operator ID to retrieve hours for.

Opening Hours

Parameter Type Description
hours_id integer The ID of the opening hours. If these are standard opening hours for this day of the week and/or operator, hours_id will be 0.
closed boolean If true, the company is closed on this day. If false, the company is open.
company_id integer The company ID of the opening hours.
day string The day of the week of the opening hours.
duration integer The duration of the opening hours, in minutes.
operator_id integer The operator ID of the opening hours.
time_end string The end time of the opening hours. If these are standard opening hours for this day of the week and/or operator, ignore the date component, and only use the time.
time_start string The start time of the opening hours. If these are standard opening hours for this day of the week and/or operator, ignore the date component, and only use the time.

Rosters

Summary

Calculating the exact opening hours for a specific operator on a specific day involves several pieces of information - see Opening Hours - Summary for more information.

List

Example Request:

curl "https://apiN.simplesalon.com/v1/roster/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        "time_start":"2019-01-01T00:00:00+00:00",
        "time_end":"2019-01-02T00:00:00+00:00",
        ...
    },
    "options":
    {
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "total_rows": 1,
    "rosters": [
        {
            "roster_id": 998866,
            "company_id": 12345,
            "duration": 30,
            "operator_id": 2222,
            "time_end": "2019-01-01T11:15:00+11:00",
            "time_start": "2019-01-01T10:45:00+11:00"
        }
    ]
}

Get a list of rosters between a date range.
Returns an error if setting advanced_rostering is 0.

Note: Results are normally restricted by the ListOptions rows_per_page limit. However for requesting a single week (or less), you can set rows_per_page: -1 to return all rosters in the range.

HTTP Request

POST /v1/roster/list

Request Data

Parameter Type Description
filters RosterFilter required The filters to apply to the roster list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all rosters for a single week only.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
page_number integer The page number of these results
rows_per_page integer The number of rows per page
total_rows integer The total number of rows matching your filters. Only returned if options.return_total is true in the request.
rosters Roster[] The list of rosters matching the filters and page options.

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/roster/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "roster_id": 998866
  }'

Example Response:

{
    "success": true,
    "roster": 
    {
        "roster_id": 998866,
        "company_id": 12345,
        "duration": 30,
        "operator_id": 2222,
        "time_end": "2019-01-01T11:15:00+11:00",
        "time_start": "2019-01-01T10:45:00+11:00"
    }
}

Gets a single roster.
Returns an error if setting advanced_rostering is 0.

HTTP Request

POST /v1/roster/get

Request Data

Parameter Type Description
roster_id integer required The ID of the roster to retrieve

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
roster Roster The roster.

Models

RosterFilter

Parameter Type Description
time_start string required The date to retrieve rosters from (inclusive). Timezone offset in this field is ignored. See Dates.
time_end string required The date to retrieve rosters to (exclusive). Timezone offset in this field is ignored. See Dates.
company_id integer The company ID to retrieve rosters for. If omitted, defaults to the logged in user's company ID.
exclude_dome boolean If in a Dome, setting to true will only return rosters for the selected company. If omitted, defaults to false, returning rosters for the selected company's operators across all locations. Ignored for standalone locations.
operator_id integer The operator ID to retrieve rosters for.

Roster

Parameter Type Description
roster_id integer The ID of the roster.
company_id integer The company ID of the roster.
duration integer The duration of the roster, in minutes.
operator_id integer The operator ID of the roster.
roster_type_id integer The ID of the roster type.
roster_type Roster Type The roster type.
time_end string The end time of roster.
time_start string The start time of the roster.

Roster Types

List

Example Request:

curl "https://apiN.simplesalon.com/v1/roster_type/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "options":
    {
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "total_rows": 1,
    "roster_types": [
        {
            "roster_type_id": 9966,
            "name": "Morning Shift",
            "colour": "ff0000",
            "allow_bookings": true,
        }
    ]
}

Get a list of roster types.
Returns an error if setting advanced_rostering is 0.

HTTP Request

POST /v1/roster_type/list

Request Data

Parameter Type Description
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all rosters for a single week only.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
page_number integer The page number of these results
rows_per_page integer The number of rows per page
total_rows integer The total number of rows matching your filters. Only returned if options.return_total is true in the request.
roster_types Roster Type[] The list of roster types matching the page options.

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/roster_type/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "roster_type_id": 9966
  }'

Example Response:

{
    "success": true,
    "roster_type": 
    {
        "roster_type_id": 9966,
        "name": "Morning Shift",
        "colour": "ff0000",
        "allow_bookings": true,
    }
}

Gets a single roster type.
Returns an error if setting advanced_rostering is 0.

HTTP Request

POST /v1/roster_type/get

Request Data

Parameter Type Description
roster_type_id integer required The ID of the roster type to retrieve

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
roster_type Roster Type The roster type.

Models

Roster Type

Parameter Type Description
roster_type_id integer The ID of the roster type.
colour string The hex colour code of the roster type.
company_id integer The company ID of the roster type.
name string The name of the roster type.
allow_bookings boolean If true, bookings are allowed during a Roster of this roster type. If false, bookings are not allowed during a roster of this roster type.

Resources

List

Example Request:

curl "https://apiN.simplesalon.com/v1/resource/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        ...
    },
    "options":
    {
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "resources": [
        {
            "company_id": 12345,
            "name": "IPL Machine",
            "description": "",
            "resource_id": 2929
        },
        ...
    ]
}

Get a list of resources.

HTTP Request

POST /v1/resource/list

Request Data

Parameter Type Description
filters ResourceFilter required The filters to apply to the resource list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all resources.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
resources Resource[] The list of resources matching the filters.

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/resource/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "resource_id": 2929
  }'

Example Response:

{
    "success": true,
    "resource": 
    {
        "company_id": 12345,
        "name": "IPL Machine",
        "description": "",
        "resource_id": 2929
    }
}

Gets a single resource.

HTTP Request

POST /v1/resource/get

Request Data

Parameter Type Description
resource_id integer required The ID of the resource to retrieve

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
resource Resource The resource.

Models

Resource

Parameter Type Description
company_id integer The company ID of the operator.
description string The description of the resource.
name string The name of the resource.
resource_id integer The ID of the resource.

ResourceFilter

Parameter Type Description
company_id integer The company ID to retrieve resources for. If omitted, defaults to the logged in user's company ID. Dome users must specify a child location.

Products

List

Example Request:

curl "https://apiN.simplesalon.com/v1/product/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        "brand_id": 0,
        ...
    },
    "options":
    {
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "products": [
        {
            "brand_id": 4444,
            "name": "Shampoo",
            "price": 10.00,
            "product_id": 5555
        },
        ...
    ]
}

Get a list of products.

HTTP Request

POST /v1/product/list

Request Data

Parameter Type Description
filters ProductFilter required The filters to apply to the product list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all products in a specific brand.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
products Product[] The list of products matching the filters.

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/product/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "product_id": 4444
  }'

Example Response:

{
    "success": true,
    "product": 
    {
        "barcode": "",
        "brand_id": 4444,
        "name": "Shampoo",
        "price": 10.00,
        "product_id": 5555
    }
}

Gets a single product.

HTTP Request

POST /v1/product/get

Request Data

Parameter Type Description
product_id integer required The ID of the product to retrieve

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
product Product The product.

Add

Example Request:

curl "https://apiN.simplesalon.com/v1/product/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "product": 
    {
        "name": "Conditioner",
        "price": 12.50,
        "quantity": 0,
        "brand_id": 4444
    }
  }'

Example Response:

{
    "success": true,
    "product": 
    {
        "brand_id": 4444,
        "name": "Conditioner",
        "price": 12.50,
        "product_id": 5556,
        "quantity": 0
    }
}

Adds a new product.

HTTP Request

POST /v1/product/add

Request Data

Parameter Type Description
product Product required The product to add.
Field Notes for Add
product_id This field must be omitted.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
product Product The new product.

Update

Example Request:

curl "https://apiN.simplesalon.com/v1/product/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "product": 
    {
        "product_id": 5556,
        "name": "Kids Conditioner"
    }
  }'

Example Response:

{
    "success": true,
    "product": 
    {
        "brand_id": 4444,
        "name": "Kids Conditioner",
        "price": 12.50,
        "product_id": 5556,
        "quantity": 0
    }
}

Updates a product.

HTTP Request

POST /v1/product/update

Request Data

Parameter Type Description
product Product required The product to update. Must specify product_id. Omitted or null fields are left unchanged.
update_in_child_locations ProductChildField If you are updating a Dome product, you can optionally specify each field to overwrite on the child products as well. If omitted, these fields will not be copied down. Fields not included in this list are always copied down, as they cannot be separately edited by the child location.
Field Notes for Update
product_id This field cannot be changed.
company_id This field cannot be changed.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
product Product The updated product.

Delete

Example Request:

curl "https://apiN.simplesalon.com/v1/product/delete"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "product_id": 5556
  }'

Example Response:

{
    "success": true
}

Deletes a product.

HTTP Request

POST /v1/product/delete

Request Data

Parameter Type Description
product_id integer required The ID of the product to delete

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).

Brand List

Example Request:

curl "https://apiN.simplesalon.com/v1/brand/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "brands": [
        {
            "brand_id": 4444,
            "name": "Hair Products"
        },
        ...
    ]
}

Get a list of product brands.

HTTP Request

POST /v1/brand/list

Request Data

Parameter Type Description
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all brands.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
brands Brand[] The list of brands for the company.

Supplier List

Example Request:

curl "https://apiN.simplesalon.com/v1/supplier/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "suppliers": [
        {
            "supplier_id": 6666,
            "name": "Excellent Hair Products"
        },
        ...
    ]
}

Get a list of product suppliers.

HTTP Request

POST /v1/supplier/list

Request Data

Parameter Type Description
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all suppliers.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
suppliers Supplier[] The list of suppliers for the company.

Models

Product

Parameter Type Description
product_id integer The ID of the product.
barcode string The barcode of the product.
brand_id integer The brand ID.
brand Brand Expanded field of brand_id. The product's brand.
company_id integer The company ID of the product.
dome_product_id integer The ID of the product in the Dome.
loyalty_points_earned integer The amount of loyalty points earned from purchasing this product.
min_quantity integer The minimum quantity you aim to have in stock.
name string The name of the product.
price decimal The price of the product.
quantity integer The quantity you currently have in stock.
reorder_quantity integer The quantity to automatically re-order.
company_use_only boolean If true, this product is only for use by the company (eg. for a bulk container of Shampoo). If false, it can be both sold to clients, or used by the company.
supplier_code string The supplier's code for this product.
supplier_id integer The supplier ID.
supplier Supplier Expanded field of supplier_id. The product's supplier.
tax_free boolean If true, this product does not have tax applied.
wholesale_price decimal The cost price of the product from your supplier.

Brand

Parameter Type Description
brand_id integer The ID of the brand.
name string The name of the brand.

Supplier

Parameter Type Description
supplier_id integer The ID of the supplier.
name string The name of the supplier.
contact_name string The name of the contact at the supplier.
phone string The phone number of the supplier.
email string The email address of the supplier.
mobile string The mobile number of the supplier.
fax string The fax number of the supplier.
address_line1 string The street address of the supplier's postal address.
address_suburb string The suburb of the supplier's postal address.
address_postcode string The postcode/zipcode of the supplier's postal address.
address_state_id integer The geographical state ID of the supplier's postal address.
address_state State Expanded field of address_state_id. The geographical state of the supplier's postal address.

ProductFilter

Parameter Type Description
company_id integer The company ID to retrieve products for. If omitted, defaults to the logged in user's company ID.
barcode string The barcode to search for - must be an exact match. If omitted, returns all.
brand_id integer The brand ID to filter by. If omitted, returns all.
dome_product_id integer The dome product ID to filter by. This will return the child location product, if it exists in the specified company. If omitted, returns all.

ProductChildField

If any fields are omitted, they will default to false.

Parameter Type Description
quantity boolean If true, the Dome product's quantity will be copied down to each child location product.
min_quantity boolean If true, the Dome product's minimum quantity will be copied down to each child location product.
reorder_quantity boolean If true, the Dome product's reorder quantity will be copied down to each child location product.
price boolean If true, the Dome product's price will be copied down to each child location product.
wholesale_price boolean If true, the Dome product's wholesale price will be copied down to each child location product.
supplier_id boolean If true, the Dome product's supplier ID will be copied down to each child location product.
loyalty_points_earned boolean If true, the Dome product's loyalty points earned value will be copied down to each child location product.

Client Products

Delete

Example Request:

curl "https://apiN.simplesalon.com/v1/client_product/delete"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_product_id": 2569
  }'

Example Response:

{
    "success": true
}

Deletes a client product.

HTTP Request

POST /v1/client_product/delete

Request Data

Parameter Type Description
client_product_id integer required The ID of the client product to delete

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).

Models

Client Product

Parameter Type Description
client_product_id integer The ID of the client product.
product_id integer The ID of the product sold to the client.
client_id integer The ID of the client the product was sold to.
company_id integer The company ID of the client product.
discount_type_id integer The discount type ID of the client product, or 0 for none.
operator_id integer The ID of the operator who sold the product.
pos_id string Your unique identifier for an unsaved client product. Only used in the Add Transaction API call.
pos_original_price decimal The original or standard price of the product total (ie. the product's price multiplied by the client product's quantity), before any discount is applied. Only set when using POS or Transaction API calls.
price decimal The price of the client product. This is the price of the total of all items in this line, including any discounts - eg. for a product worth 10.00, with quantity of 2 and a 25% discount, price will be 15.00.
product Product A minimal Product object, to provide the product name and brand name.
quantity integer The quantity of product sold to the client.
tax_rate decimal The tax rate percentage applied to the client product.
transaction_id integer The transaction ID of the client product, or 0 for none.
can_redeem_via_package boolean If true, this client product could be redeemed by claiming one of the client's previously purchased (and as yet unclaimed) package items. This field is only included when relevant (ie. with a POS-related API call).

Vouchers

List

Example Request:

curl "https://apiN.simplesalon.com/v1/voucher/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        ...
    },
    "options":
    {
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "vouchers": [
        {
            "expiry_number": 3,
            "expiry_type": "months",
            "loyalty_points_earned": 0,
            "name": "$100 Gift Voucher",
            "price": 100,
            "type": "cash",
            "value": 100,
            "voucher_id": 7777
        },
        ...
    ]
}

Get a list of vouchers.

HTTP Request

POST /v1/voucher/list

Request Data

Parameter Type Description
filters VoucherFilter required The filters to apply to the voucher list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all vouchers.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
vouchers Voucher[] The list of vouchers matching the filters.

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/voucher/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "voucher_id": 7777
  }'

Example Response:

{
    "success": true,
    "voucher": 
    {
        "expiry_number": 3,
        "expiry_type": "months",
        "loyalty_points_earned": 0,
        "name": "$100 Gift Voucher",
        "price": 100,
        "type": "cash",
        "value": 100,
        "voucher_id": 7777
    }
}

Gets a single voucher.

HTTP Request

POST /v1/voucher/get

Request Data

Parameter Type Description
voucher_id integer required The ID of the voucher to retrieve

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
voucher Voucher The voucher.

Add

Example Request:

curl "https://apiN.simplesalon.com/v1/voucher/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "voucher": 
    {
        "name": "$50 voucher",
        "type":"cash",
        "price": 50,
        "value": 50
    }
  }'

Example Response:

{
    "success": true,
    "voucher": 
    {
        "name": "$50 voucher",
        "type": "cash",
        "price": 50,
        "value": 50
        "voucher_id": 7778
    }
}

Adds a new voucher.

HTTP Request

POST /v1/voucher/add

Request Data

Parameter Type Description
voucher Voucher required The voucher to add.
Field Notes for Add
voucher_id This field must be omitted.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
voucher Voucher The new voucher.

Update

Example Request:

curl "https://apiN.simplesalon.com/v1/voucher/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "voucher": 
    {
        "voucher_id": 7778,
        "name": "$55 voucher",
        "value": 55
    }
  }'

Example Response:

{
    "success": true,
    "voucher": 
    {
        "name": "$55 voucher",
        "type": "cash",
        "price": 50,
        "value": 55
        "voucher_id": 7778
    }
}

Updates a voucher.

HTTP Request

POST /v1/voucher/update

Request Data

Parameter Type Description
voucher Voucher required The voucher to update. Must specify voucher_id. Omitted or null fields are left unchanged.
update_in_child_locations VoucherChildField If you are updating a Dome voucher, you can optionally specify each field to overwrite on the child vouchers as well. If omitted, these fields will not be copied down. Fields not included in this list are always copied down, as they cannot be separately edited by the child location.
Field Notes for Update
voucher_id This field cannot be changed.
company_id This field cannot be changed.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
voucher Voucher The updated voucher.

Delete

Example Request:

curl "https://apiN.simplesalon.com/v1/voucher/delete"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "voucher_id": 7778
  }'

Example Response:

{
    "success": true
}

Deletes a voucher.

HTTP Request

POST /v1/voucher/delete

Request Data

Parameter Type Description
voucher_id integer required The ID of the voucher to delete

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).

Voucher Item List

Example Request:

curl "https://apiN.simplesalon.com/v1/voucher/item/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":{
        "voucher_id":7779
    },
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "voucher_items": [
        {
            "quantity": 1,
            "service_id": 3333,
            "type": "service",
            "voucher_item_id": 8888
        },
        ...
    ]
}

Get a list of items that are included in an item voucher.

HTTP Request

POST /v1/voucher/item/list

Request Data

Parameter Type Description
filters VoucherItemFilter required The filters to apply to the voucher item list
options ListOptions The options for list results.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
voucher_items VoucherItem[] The list of voucher items included in the voucher.

Models

Voucher

Parameter Type Description
voucher_id integer The ID of the voucher.
barcode string The barcode of the voucher.
company_id integer The company ID of the voucher.
dome_voucher_id integer The ID of the voucher in the Dome.
loyalty_points_earned integer The amount of loyalty points earned from purchasing this voucher.
name string The name of the voucher.
price decimal The price of the voucher.
type string The voucher type. Valid values are cash or item.
value decimal The value of a cash type voucher.
expiry_number integer The number value of the voucher expiry. Eg. for a voucher expiring in 5 weeks, it would be 5.
expiry_type string The period of the voucher expiry. Valid values are never, days, weeks, months or years. Eg. for a voucher expiring in 5 weeks, it would be weeks.

VoucherFilter

Parameter Type Description
company_id integer The company ID to retrieve vouchers for. If omitted, defaults to the logged in user's company ID.
dome_voucher_id integer The dome voucher ID to filter by. This will return the child location voucher, if it exists in the specified company. If omitted, returns all.
exclude_variable_voucher bool If true, the Variable Voucher is excluded from the results list. If omitted, defaults to false, which will return the Variable Voucher as part of the results list.

VoucherChildField

If any fields are omitted, they will default to false.

Parameter Type Description
price boolean If true, the Dome voucher's price will be copied down to each child location voucher.
loyalty_points_earned boolean If true, the Dome voucher's loyalty points earned value will be copied down to each child location voucher.

VoucherItem

Parameter Type Description
voucher_item_id integer The ID of the voucher item.
product_id integer The ID of the product (if the type is a product).
quantity integer The number of this item included in the voucher.
service_id integer The ID of the service (if the type is a service).
type string The type of this item. Valid values are product or service.

VoucherItemFilter

Parameter Type Description
voucher_id integer required The voucher ID to retrieve voucher items for.

Special Values

Variable Voucher

A voucher_id value of -1 indicates a Variable Voucher. This voucher is created specifically for the client at sale: value field must be set, and if the setting variable_voucher_editable is true, you must also specify the expiry_date or omit it for never. If variable_voucher_editable is false, then expiry_date will be ignored - the voucher's expiry will be set to the default.

Client Vouchers

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/client_voucher/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_voucher_id": 2769
  }'

Example Response:

{
    "success": true,
    "client_voucher": 
    {
        "barcode": "900000000123",
        "client_id": 1111,
        "client_voucher_id": 2769,
        "company_id": 12345,
        "operator_id": 2222,
        "price": 50,
        "transaction_id": 85735,
        "type": "cash",
        "value": 50,
        "voucher": {
            "name": "$50 voucher",
            "type": "cash",
            "price": 50,
            "voucher_id": 7778
        },
        "voucher_id": 7778
    }
}

Gets a single client voucher.

HTTP Request

POST /v1/client_voucher/get

Request Data

Parameter Type Description
client_voucher_id integer required The ID of the client voucher to retrieve

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
client_voucher ClientVoucher The client voucher.

Models

Client Voucher

Parameter Type Description
barcode string The barcode of the gift voucher.
client_voucher_id integer The ID of the client voucher.
client_id integer The ID of the client the voucher was sold to.
company_id integer The company ID of the client voucher.
discount_type_id integer The discount type ID of the client voucher, or 0 for none.
expiry_date string The expiry date of the client voucher. Omitted if the voucher never expires.
operator_id integer The ID of the operator who sold the voucher.
pos_id string Your unique identifier for an unsaved client voucher. Only used in the Add Transaction API call.
pos_original_price decimal The original or standard price of the voucher, before any discount is applied. Only set when using POS or Transaction API calls.
price decimal The price of the client voucher.
transaction_id integer The transaction ID of the client voucher, or 0 for none.
type string The voucher type. Valid values are cash or item.
value decimal The remaining value of a cash type voucher.
voucher_id integer The ID of the voucher sold to the client.
voucher Voucher A minimal Voucher object, to provide the voucher name.

Packages

List

Example Request:

curl "https://apiN.simplesalon.com/v1/package/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        ...
    },
    "options":
    {
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "packages": [
        {
            "barcode": "",
            "loyalty_points_earned": 0,
            "name": "10 x Haircut",
            "package_id": 9999,
            "price": 85,
            "tax_free": false
        },
        ...
    ]
}

Get a list of packages.

HTTP Request

POST /v1/package/list

Request Data

Parameter Type Description
filters PackageFilter required The filters to apply to the package list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all packages.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
packages Package[] The list of packages matching the filters.

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/package/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "package_id": 9999
  }'

Example Response:

{
    "success": true,
    "package": 
    {
        "barcode": "",
        "loyalty_points_earned": 0,
        "name": "10 x Haircut",
        "package_id": 9999,
        "price": 85,
        "tax_free": false
    }
}

Gets a single package.

HTTP Request

POST /v1/package/get

Request Data

Parameter Type Description
package_id integer required The ID of the package to retrieve

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
package Package The package.

Add

Example Request:

curl "https://apiN.simplesalon.com/v1/package/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "package": 
    {
        "barcode": "",
        "loyalty_points_earned": 0,
        "name": "2 for 1 Beard Trim",
        "price": 20,
        "tax_free": false
    }
  }'

Example Response:

{
    "success": true,
    "package": 
    {
        "barcode": "",
        "loyalty_points_earned": 0,
        "name": "2 for 1 Beard Trim",
        "package_id": 9998,
        "price": 20,
        "tax_free": false
    }
}

Adds a new package.

HTTP Request

POST /v1/package/add

Request Data

Parameter Type Description
package Package required The package to add.
Field Notes for Add
package_id This field must be omitted.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
package Package The new package.

Update

Example Request:

curl "https://apiN.simplesalon.com/v1/package/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "package": 
    {
        "package_id": 9998,
        "name": "2 x Beard Trim"
    }
  }'

Example Response:

{
    "success": true,
    "package": 
    {
        "barcode": "",
        "loyalty_points_earned": 0,
        "name": "2 x Beard Trim",
        "package_id": 9998,
        "price": 20,
        "tax_free": false
    }
}

Updates a package.

HTTP Request

POST /v1/package/update

Request Data

Parameter Type Description
package Package required The package to update. Must specify package_id. Omitted or null fields are left unchanged.
update_in_child_locations PackageChildField If you are updating a Dome package, you can optionally specify each field to overwrite on the child packages as well. If omitted, these fields will not be copied down. Fields not included in this list are always copied down, as they cannot be separately edited by the child location.
Field Notes for Update
package_id This field cannot be changed.
company_id This field cannot be changed.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
package Package The updated package.

Delete

Example Request:

curl "https://apiN.simplesalon.com/v1/package/delete"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "package_id": 9998
  }'

Example Response:

{
    "success": true
}

Deletes a package.

HTTP Request

POST /v1/package/delete

Request Data

Parameter Type Description
package_id integer required The ID of the package to delete

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).

Package Item List

Example Request:

curl "https://apiN.simplesalon.com/v1/package/item/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":{
        "package_id":9999
    },
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "package_items": [
        {
            "quantity": 10,
            "service_id": 3333,
            "type": "service",
            "package_item_id": 8888
        },
        ...
    ]
}

Get a list of items that are included in a package.

HTTP Request

POST /v1/package/item/list

Request Data

Parameter Type Description
filters PackageItemFilter required The filters to apply to the package item list
options ListOptions The options for list results.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
package_items PackageItem[] The list of package items included in the package.

Models

Package

Parameter Type Description
package_id integer The ID of the package.
barcode string The barcode of the package.
company_id integer The company ID of the package.
dome_package_id integer The ID of the package in the Dome.
loyalty_points_earned integer The amount of loyalty points earned from purchasing this package.
name string The name of the package.
price decimal The price of the package.
tax_free boolean If true, this package does not have tax applied.

PackageFilter

Parameter Type Description
company_id integer The company ID to retrieve packages for. If omitted, defaults to the logged in user's company ID.
dome_package_id integer The dome package ID to filter by. This will return the child location package, if it exists in the specified company. If omitted, returns all.

PackageChildField

If any fields are omitted, they will default to false.

Parameter Type Description
price boolean If true, the Dome package's price will be copied down to each child location package.
loyalty_points_earned boolean If true, the Dome package's loyalty points earned value will be copied down to each child location package.

PackageItem

Parameter Type Description
package_item_id integer The ID of the package item.
product_id integer The ID of the product (if the type is a product).
quantity integer The number of this item included in the package.
service_id integer The ID of the service (if the type is a service).
type string The type of this item. Valid values are product or service.

PackageItemFilter

Parameter Type Description
package_id integer required The package ID to retrieve package items for.

Client Packages

Delete

Example Request:

curl "https://apiN.simplesalon.com/v1/client_package/delete"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_package_id": 2669
  }'

Example Response:

{
    "success": true
}

Deletes a client package.

HTTP Request

POST /v1/client_package/delete

Request Data

Parameter Type Description
client_package_id integer required The ID of the client package to delete

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).

Models

Client Package

Parameter Type Description
client_package_id integer The ID of the client package.
package_id integer The ID of the package sold to the client.
client_id integer The ID of the client the package was sold to.
company_id integer The company ID of the client package.
discount_type_id integer The discount type ID of the client package, or 0 for none.
operator_id integer The ID of the operator who sold the package.
pos_id string Your unique identifier for an unsaved client package. Only used in the Add Transaction API call.
pos_original_price decimal The original or standard price of the package, before any discount is applied. Only set when using POS or Transaction API calls.
price decimal The price of the client package.
package Package A minimal Package object, to provide the package name.
tax_rate decimal The tax rate percentage applied to the client package.
transaction_id integer The transaction ID of the client package, or 0 for none.

Memberships

List

Example Request:

curl "https://apiN.simplesalon.com/v1/membership/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        ...
    },
    "options":
    {
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "memberships": [
        {
            "checkin_allowance_period_type": "start_date",
            "checkin_allowance_type": "unlimited",
            "checkin_service_id": 3333,
            "company_id": 12345,
            "expiry_type": "never",
            "membership_id": 4646,
            "minimum_cancellation_type": "none",
            "name": "1 Year Upfront",
            "payment_type": "upfront",
            "setup_fee": 100.00,
            "suspension_allowed": true,
            "tax_free": true
        },
        ...
    ]
}

Get a list of memberships.

HTTP Request

POST /v1/membership/list

Request Data

Parameter Type Description
filters MembershipFilter required The filters to apply to the membership list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all memberships.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
memberships Membership[] The list of memberships matching the filters.

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/membership/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "membership_id": 4646
  }'

Example Response:

{
    "success": true,
    "membership": 
    {
        "checkin_allowance_period_type": "start_date",
        "checkin_allowance_type": "unlimited",
        "checkin_service_id": 3333,
        "company_id": 12345,
        "expiry_type": "never",
        "membership_id": 4646,
        "minimum_cancellation_type": "none",
        "name": "1 Year Upfront",
        "payment_type": "upfront",
        "setup_fee": 100.00,
        "suspension_allowed": true,
        "tax_free": true
    }
}

Gets a single membership.

HTTP Request

POST /v1/membership/get

Request Data

Parameter Type Description
membership_id integer required The ID of the membership to retrieve

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
membership Membership The membership.

Models

Membership

Parameter Type Description
membership_id integer The ID of the membership.
dome_membership_id integer The ID of the membership in the Dome.
name string The name of the membership.
setup_fee decimal The joining fee, charged at sale.
payment_type string The payment type of the membership. Valid values are upfront and recurring.
recurring_fee decimal The recurring fee, charged each recurring_type. Omitted if payment_type is upfront.
recurring_type string The recurring period length. Valid values are weekly, fortnightly, monthly or fourweekly. Omitted if payment_type is upfront.
tax_free boolean If true, this membership does not have tax applied.
suspension_allowed boolean If true, this type of membership can be suspended.
expiry_number integer The expiry length, in combination with expiry_type. Omitted if expiry_type is never.
expiry_type string The expiry length, in combination with expiry_number. Valid values are never, days, weeks, months or years.
checkin_allowance_number integer The amount of check in visits included in the membership, in combination with checkin_allowance_type.
checkin_allowance_type string The amount of check in visits included in the membership, in combination with checkin_allowance_number. Valid values are unlimited, perday, perweek, permonth or peryear.
checkin_allowance_period_type string When to reset the amount of check in visits for the next, in combination with checkin_allowance_type period. Valid values are calendar or start_date. Eg. if the membership was sold on a Thursday with a perweek check in allowance, then calendar would reset the allowance each Sunday, whereas start_date would reset the allowance every Thursday.
checkin_service_id integer The service ID to record when the client checks in.
minimum_cancellation_number decimal The minimum cancellation period length, in combination with minimum_cancellation_type. Omitted if minimum_cancellation_type is none.
minimum_cancellation_type string The minimum cancellation period length. Valid values are none, weeks or months.
minimum_suspension_number decimal The minimum suspension period length, in combination with minimum_suspension_type. Omitted if suspension_allowed is false or minimum_suspension_type is none.
minimum_suspension_type string The minimum suspension period length. Valid values are none, weeks or months. Omitted if suspension_allowed is false.
maximum_suspension_number decimal The maximum suspension period length, in combination with maximum_suspension_type. Omitted if suspension_allowed is false or maximum_suspension_type is none.
maximum_suspension_type string The maximum suspension period length. Valid values are none, weeks or months. Omitted if suspension_allowed is false.

MembershipFilter

Parameter Type Description
company_id integer The company ID to retrieve memberships for. If omitted, defaults to the logged in user's company ID.
dome_membership_id integer The dome membership ID to filter by. This will return the child location membership, if it exists in the specified company. If omitted, returns all.

Client Memberships

Delete

Example Request:

curl "https://apiN.simplesalon.com/v1/client_membership/delete"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_membership_id": 2469
  }'

Example Response:

{
    "success": true
}

Deletes a client membership.

HTTP Request

POST /v1/client_membership/delete

Request Data

Parameter Type Description
client_membership_id integer required The ID of the client membership to delete

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).

Models

Client Membership

Parameter Type Description
client_membership_id integer The ID of the client membership.
membership_id integer The ID of the membership sold to the client.
client_id integer The ID of the client the membership was sold to.
company_id integer The company ID of the client membership.
discount_type_id integer The discount type ID of the client membership, or 0 for none.
operator_id integer The ID of the operator who sold the membership.
pos_id string Your unique identifier for an unsaved client membership. Only used in the Add Transaction API call.
price decimal The price of the client membership, before any discounts.
membership Membership A minimal Membership object, to provide the membership name.
start_date string The start date of the client membership.
transaction_id integer The transaction ID of the client membership, or 0 for none.
use_direct_debit boolean true if the client will be linked up to an automatic direct debit addon, false if not. Defaults to false.

Discount Types

List

Example Request:

curl "https://apiN.simplesalon.com/v1/discount_type/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "options":
    {
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "discount_types": [
        {
            "amount": 10,
            "apply_automatically": false,
            "company_id": 12345,
            "discount_type": "%",
            "discount_type_id": 7171,
            "name": "10% off"
        },
        ...
    ]
}

Get a list of discount types.

HTTP Request

POST /v1/discount_type/list

Request Data

Parameter Type Description
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all discount types.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
discount_types DiscountType[] The list of discount types.

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/discount_type/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "discount_type_id": 7171
  }'

Example Response:

{
    "success": true,
    "discount_type": 
    {
            "amount": 10,
            "apply_automatically": false,
            "company_id": 12345,
            "discount_type": "%",
            "discount_type_id": 7171,
            "name": "10% off"
        }
}

Gets a single discount type.

HTTP Request

POST /v1/discount_type/get

Request Data

Parameter Type Description
discount_type_id integer required The ID of the discount type to retrieve

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
discount_type DiscountType The discount type.

Models

Discount Type

Parameter Type Description
discount_type_id integer The ID of the discount type.
amount decimal The amount of the discount type.
company_id integer The company ID of the discount type.
discount_type string The type of discount. Valid values are $ and %.
name string The name of the discount type.

Special Values

System Discount

A discount_type_id value of -1 indicates a System Discount. The System Discount can only be set by the system (it cannot be set by the user), and if an item has a System Discount applied, it cannot be changed to another type of discount.

System Discount reasons can include (but are not limited to):

Settings

List

Example Request:

curl "https://apiN.simplesalon.com/v1/setting/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        "setting_keys": ["client_hide_address"]
    }
  }'

Example Response:

{
    "success": true,
    "settings": [
        {
            "name": "client_hide_address",
            "value": "1"
        },
        ...
    ]
}

Get a list of settings. All requested settings will be returned (there is no paging).

HTTP Request

POST /v1/setting/list

Request Data

Parameter Type Description
filters SettingFilter required The filters to apply to the setting list

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
settings Setting[] The list of settings matching the filters.

Client List

Example Request:

curl "https://apiN.simplesalon.com/v1/setting/client/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
    }
  }'

Example Response:

{
    "success": true,
    "settings": [
        {
            "name": "client_hide_address",
            "value": "1"
        },
        ...
    ],
    "default_categories": [
        {
            "client_category_id": 1,
            "name": "Loyalty Program"
        }
    ]
}

Get a list of settings related to adding or editing clients, as well as the default Client Category list for new clients. All requested settings will be returned (there is no paging).

HTTP Request

POST /v1/setting/client/list

Request Data

Parameter Type Description
filters ClientSettingFilter The filters to apply to the setting list

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
settings Setting[] The list of settings specific to adding/editing clients.
default_categories ClientCategory[] The list of client categories to automatically add to new clients.

POS List

Example Request:

curl "https://apiN.simplesalon.com/v1/setting/pos/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
    }
  }'

Example Response:

{
    "success": true,
    "settings": [
        {
            "name": "force_operator_at_sale",
            "value": "0"
        },
        {
            "name": "auto_scan",
            "value": "0"
        },
        {
            "name": "advanced_discounting",
            "value": "1"
        },
        {
            "name": "prices_inc_tax",
            "value": "1"
        },
        {
            "name": "enable_tips",
            "value": "1"
        },
        {
            "name": "automatic_tip_percentage",
            "value": "15"
        },
        {
            "name": "rebook_reminder",
            "value": "1"
        }
    ],
    "currency_symbol": "$",
    "current_operator_id": 2222,
    "operators": [
        {
            "company_id": 12345,
            "display_name": "Ash",
            "firstname": "Ashley",
            "lastname": "Smith",
            "level": {
                "level_id": 100,
                "name": "Apprentice"
            },
            "level_id": 100,
            "operator_id": 2222,
            "order_num": 0
        },
        ...
    ],
    "tax_combined_name": "GST",
    "tax_for_packages": {
        "company_id": 12345,
        "name": "GST",
        "rate": 10,
        "tax_id": 8008
    },
    "tax_for_products": {
        "company_id": 12345,
        "name": "GST",
        "rate": 10,
        "tax_id": 8008
    },
    "tax_for_services": {
        "company_id": 12345,
        "name": "GST",
        "rate": 10,
        "tax_id": 8008
    },
    "tax_for_vouchers": {
        "company_id": 12345,
        "name": "GST",
        "rate": 10,
        "tax_id": 8008
    },
    "variable_voucher_default_expiry_number": 0,
    "variable_voucher_default_expiry_type": "never",
    "variable_voucher_editable": false
}

Get a list of settings related to POS, as well as the Operator list for POS. All requested settings will be returned (there is no paging).

HTTP Request

POST /v1/setting/pos/list

Request Data

Parameter Type Description
filters POSSettingFilter The filters to apply to the setting list

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
settings Setting[] The list of settings specific to POS.
currency_symbol string The currency symbol to use when displaying prices.
current_operator_id integer The ID of the current operator, to select by default (if it appears in the operators list).
operators Operator[] The list of operators available at POS.
tax_combined_name string The name to use when referring to all taxes - ie. the total of all taxes at POS.
tax_for_memberships Tax The tax to apply to memberships (excluding memberships marked tax_free)
tax_for_packages Tax The tax to apply to packages (excluding packages marked tax_free)
tax_for_products Tax The tax to apply to products (excluding products marked tax_free)
tax_for_services Tax The tax to apply to services (excluding services marked tax_free)
tax_for_vouchers Tax The tax to apply to vouchers (excluding vouchers marked tax_free)
variable_voucher_default_expiry_number integer The number value of the default Variable Voucher expiry. Eg. for a voucher expiring in 5 weeks, it would be 5.
variable_voucher_default_expiry_type string The period of the default Variable Voucher expiry. Valid values are never, days, weeks, months or years. Eg. for a voucher expiring in 5 weeks, it would be weeks.
variable_voucher_editable boolean If true, the current user is allowed to adjust the included value and expiry of a Variable Voucher at sale. If false, the value must match the price, and the expiry cannot be changed from the default.

Available Settings

All settings are returned as string values, the Type is how you should interpret the setting value. Boolean type settings will return 0 or 1.

Setting Key Type Description
advanced_discounting boolean If 1, Advanced Discounting is enabled, allowing the use of preset Discount Types. If 0, the discount can be manually specified on an item as a percentage.
advanced_rostering boolean If 1, Advanced Rostering is enabled, allowing setting individual Rosters of different Roster Types per day. If 0, the opening hours of the company will be returned as rosters with roster_id on each set to 0.
appointment_interval integer The minimum time for an appointment timeslot.
auto_roster_off boolean If 1, then bookings cannot be made unless a roster specifically allows it. If 0, then bookings can be made even if there is no specific roster to allow it, as long as there isn't a roster disallowing it. If advanced_rostering is disabled, this setting is ignored.
auto_scan boolean If 1, the scan service/product barcode option should be automatically loaded when POS is loaded.
automatic_tip_percentage decimal The percentage Tip to automatically apply.
client_hide_address boolean If 1, Staff members cannot view or edit address details for a client. They will be able to add address details for a new client.
client_hide_phone boolean If 1, Staff members cannot view or edit telephone or mobile details for a client. They will be able to add phone details for a new client.
client_requires_mobile boolean If 1, the Mobile field is required for a client
client_requires_email boolean If 1, the Email field is required for a client
client_sharing_enabled boolean Only relevant for Dome and child locations. If 1, the location allows client sharing with other locations in the Dome who are also sharing clients.
enable_tips boolean Whether to enable adding Tips at POS.
force_operator_at_sale boolean If 1, each item in the sale must be assigned to an operator. If 0, the operator can be omitted (which assigns those items to the System Operator).
new_client_promotions_default boolean If 1, the SMS Promotion and Email Promotion values should default to true for a client.
new_client_reminders_default boolean If 1, the SMS Reminder and Email Reminder values should default to true for a client.
prices_inc_tax boolean If 1, the prices of items at POS already includes any relevant tax component (so the tax does not increase the total of the sale). If 0, the tax is added on to the item's price (and increases the total of the sale).
rebook_reminder boolean If 1, the user should be prompted to rebook any appointments sold at POS.
search_dome_clients_default boolean Only relevant for Dome and child locations. If 1, the Search Dome field for client search should default to true.
timezone string The timezone for the requested company. Timezone result will be an option from the Microsoft Default Timezones list. See also Timezones. Requesting the timezone setting will also always return the timezone_iana setting as well.
timezone_iana string The timezone for the requested company, converted to the best-fit IANA timezone. Timezone result will be an option from the IANA Timezones list. See also Timezones. Requesting the timezone_iana setting will also always return the timezone setting as well.

Models

Setting

Parameter Type Description
name string The setting key name.
value string The value of the setting.

SettingFilter

Parameter Type Description
company_id integer The company ID to retrieve settings for. If omitted, defaults to the logged in user's company ID.
setting_keys string[] required The list of settings to retrieve, from the Available Settings list

ClientSettingFilter

Parameter Type Description
company_id integer The company ID to retrieve client settings for. If omitted, defaults to the logged in user's company ID.

POSSettingFilter

Parameter Type Description
company_id integer The company ID to retrieve POS settings for. If omitted, defaults to the logged in user's company ID.

Payment Types

List

Example Request:

curl "https://apiN.simplesalon.com/v1/payment_type/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "options":
    {
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "payment_types": [
        {
            "company_id": 12345,
            "is_live": false,
            "is_system": true,
            "payment_type_id": 83838,
            "name": "Credit Card",
            "show_on_pos": true
        },
        ...
    ]
}

Get a list of payment types.

HTTP Request

POST /v1/payment_type/list

Request Data

Parameter Type Description
filters PaymentTypeFilter The filters to apply to the payment type list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all payment types.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
payment_types PaymentType[] The list of payment types.

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/payment_type/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "payment_type_id": 83838
  }'

Example Response:

{
    "success": true,
    "payment_type": 
    {
        "company_id": 12345,
        "is_live": false,
        "is_system": true,
        "payment_type_id": 83838,
        "name": "Credit Card",
        "show_on_pos": true
    }
}

Gets a single payment type.

HTTP Request

POST /v1/payment_type/get

Request Data

Parameter Type Description
payment_type_id integer required The ID of the payment type to retrieve

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
payment_type PaymentType The payment type.

Models

PaymentTypeFilter

Parameter Type Description
company_id integer The company ID to retrieve payment types for. If omitted, defaults to the logged in user's company ID.
show_on_pos boolean true for payment types that are visible on the POS screen, false for payment types that are not. If omitted, returns both.

Payment Type

Parameter Type Description
payment_type_id integer The ID of the payment type.
company_id integer The company ID of the payment type.
description string The description of the payment type.
extra_fields string[] The extra field keys required by this payment type. Common keys are change (for the Cash payment method, and Gift Voucher With No ID payment method), cashout (for the EFTPOS payment method). External gateways will have other extra fields required.
gateway string The gateway to use to process a live payment (before adding it to a Transaction). Omitted if this payment type doesn't require processing through an external gateway. If your system does not know how to process through the listed gateway, it should not offer the payment type at POS.
is_live boolean true if this payment method processes live payments, for example, an EFTPOS machine. Payments made using a live payment type cannot be voided - they must be refunded.
is_system boolean Whether this payment type is a system payment type - if true, it cannot be deleted and some fields cannot be edited.
name string The name of the payment type.
show_on_pos boolean Whether this payment type will be shown as an option on the POS screen

Live Payment Types

Afterpay

Charges the client's Afterpay account for the purchase.
Afterpay must be the only payment method in the transaction - split payment transactions are not allowed.

Request fields for Process Live Payment:

Required Fields Value
gateway afterpay
barcode The client's Afterpay barcode.

Payment is processed automatically, do not call Add Payment.

Gift Voucher

Looks up the provided gift voucher barcode against the gift vouchers sold in the system, and returns the amount that can be used.
For an item voucher, the amount returned is the total amount of the items in this transaction that can be claimed from this gift voucher - you must use the whole amount. For a cash voucher, the amount returned is the total amount remaining on the voucher - choose to use any amount equal to or less than this.

Request fields for Process Live Payment:

Required Fields Value
gateway voucher
barcode The gift voucher's barcode.

Response fields for Process Live Payment:

Extra Field Value
client_voucher_id The ID of the client voucher matching this barcode.
type The voucher type. Valid values are cash or item.
expiry_date The expiry date of the client voucher. Omitted if the voucher never expires.
purchased_by_name The name of the client who purchased this voucher.

Payment is not processed automatically - you must call Add Payment with your payment_type_id and the returned client_voucher_id and amount.

Request fields for Add Payment:

Extra Field Value
client_voucher_id The ID of the client voucher (returned from your Process Live Payment call).

Taxes

Models

Tax

Parameter Type Description
tax_id integer The ID of the tax.
company_id integer The company ID of the tax.
name string The name of the tax.
rate decimal The tax rate to apply.

POS

Load

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/load"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_id": 1111
  }'

Example Response:

{
    "success": true,
    "appointments": [
        {
            "appointment_id": 56789,
            "can_redeem_via_loyalty_points": true,
            "can_redeem_via_package": false,
            "client_id": 1111,
            "company_id": 12345,
            "duration": 15,
            "loyalty_points_to_redeem": 20,
            "operator_id": 2222,
            "resource_id": 0,
            "service": {
                "category": {
                    "category_id": 0,
                    "name": "No Category"
                },
                "category_id": 0,
                "name": "Haircut",
                "service_id": 3333
            },
            "service_id": 3333,
            "time_end": "2019-01-01T11:15:00+11:00",
            "time_start": "2019-01-01T11:00:00+11:00",
            "transaction_id": 0
        }
    ],
    "client": {
            "address_line1": "1 Example St",
            "address_postcode": "3000",
            "address_state_id": 3,
            "address_state": {
                "name": "VIC",
                "state_id": 3
            },
            "address_suburb": "Melbourne",
            "barcode": "8786745156874",
            "category_ids": [919],
            "categories": [
                {
                    "client_category_id": 919,
                    "name": "Loyalty Program"
                }
            ],
            "client_id": 1111,
            "comments": "",
            "company_id": 12345,
            "date_of_birth": "2017-10-18T00:00:00+11:00",
            "email": "",
            "email_promotions_enabled": false,
            "email_reminders_enabled": true,
            "firstname": "Joe",
            "gender": "Male",
            "lastname": "Citizen",
            "loyalty_member": true,
            "loyalty_points": 235,
            "mobile": "",
            "referral_type_id": 29,
            "referral_type": {
                "name": "Digital Advertising",
                "referral_type_id": 29
            },
            "sms_promotions_enabled": false,
            "sms_reminders_enabled": true
        }
    "client_memberships": [
        {
            "client_id": 1111,
            "client_membership_id": 6262,
            "company_id": 12345,
            "membership": {
                "membership_id": 4646,
                "name": "1 Year Upfront"
            },
            "membership_id": 4646,
            "operator_id": 2222,
            "price": 100,
            "transaction_id": 0
        }
    ],
    "client_packages": [],
    "client_products": [
        {
            "can_redeem_via_package": false,
            "client_id": 1111,
            "client_product_id": 3737,
            "company_id": 12345,
            "operator_id": 2222,
            "price": 12.50,
            "product": 
            {
                "brand": {
                    "brand_id": 4444,
                    "name": "Hair Products"
                },
                "brand_id": 4444,
                "name": "Conditioner",
                "product_id": 5556
            }
            "product_id": 5556,
            "quantity": 1,
            "transaction_id": 0
        }
    ]
}

Gets the details of the client, as well as their lists of items to add to the sale. All list items will be returned (there is no paging).

HTTP Request

POST /v1/pos/load

Request Data

Parameter Type Description
client_id integer required The ID of the client to add to the sale.
company_id integer The ID of the company using POS. If omitted, defaults to the logged in user's company ID. Dome users must specify a child location.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
appointments Appointment[] The list of appointments to add to the sale.
client Client The client.
client_packages ClientPackage[] The list of client packages to add to the sale.
client_products ClientProduct[] The list of client products to add to the sale.
client_memberships ClientMembership[] The list of client memberships to add to the sale.

Save

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/save"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "appointments": [
        {
            "client_id": 1111,
            "appointment_id": -1,
            "operator_id": -1,
            "pos_id": "myref1",
            "price": 10.03,
            "service_id": 3333
        }
    ],
    "client_memberships": [],
    "client_packages": [],
    "client_products": []
  }'

Example Response:

{
    "success": true
}

Saves all the unpaid items to the client, for retrieving later (via POS Load). If the client already has saved items, these will be added, and all saved items will be retrieved when loading.

Note that Account Values, Tips and Client Vouchers cannot be saved for later.

HTTP Request

POST /v1/pos/save

Request Data

Parameter Type Description
appointments Appointment[] The list of appointments to save.
Must specify appointment_id, client_id, operator_id, service_id, price (price is not needed for group parents).
client_packages ClientPackage[] The list of client packages to save.
Must specify client_package_id, client_id, operator_id, package_id, price.
client_products ClientProduct[] The list of client products to save.
Must specify client_product_id, client_id, operator_id, product_id, price, quantity.
client_memberships ClientMembership[] The list of client memberships to save.
Must specify client_membership_id, client_id, operator_id, package_id, price, start_date.
company_id integer The ID of the company using POS. If omitted, defaults to the logged in user's company ID. Dome users must specify a child location.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).

Service Price Check

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/service/check"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "appointment_id": -1,
    "client_id":1111,
    "operator_id": -1,
    "service_id":5555
  }'

Example Response:

{
    "success": true,
    "available_discounts": [
        {
            "amount": 10,
            "apply_automatically": false,
            "company_id": 12345,
            "discount_type": "%",
            "discount_type_id": 7171,
            "name": "10% off"
        },
        ...
    ]
    "appointment": {
        "can_redeem_via_package": true,
        "can_redeem_via_loyalty_points": true,
        "client_id": 1111,
        "appointment_id": -1,
        "company_id": 12345,
        "operator_id": -1,
        "pos_original_price": 10.00,
        "price": 10.00,
        "service": {
            "barcode": "",
            "category_id": 0,
            "name": "Haircut",
            "price": 10.00,
            "service_id": 3333
        },
        "resource_id": 0,
        "service_id": 3333,
        "tax_rate": 10
    }
}

Returns the price, tax rate, category and name of the service, plus any auto-applied discount, whether it is a group service and whether this client can redeem the product via loyalty points, or an as yet unclaimed service from a previously purchased package.

HTTP Request

POST /v1/pos/service/check

Request Data

Parameter Type Description
barcode string The barcode of the appointment to add. Must specify either barcode or service_id.
client_id integer required The ID of the client to add to the sale.
appointment_id integer required The ID of the appointment if it's an existing item. Send -1 for an item added at sale that is not yet saved to the server (see Special Values - Unsaved Item).
company_id integer The ID of the company using POS. If omitted, defaults to the logged in user's company ID. Dome users must specify a child location.
operator_id integer required The ID of the operator who performed the appointment. Send -1 for none if setting force_operator_at_sale is false.
service_id integer The ID of the service to add. Must specify either barcode or service_id.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
available_discounts DiscountType[] The list of discount types that can be applied to this appointment. Omitted if setting advanced_discounting is false.
appointment Appointment The appointment to add to the sale, with pos_original_price (before any discount), tax_rate, discount_type_id (if a discount is automatically applied), can_redeem_via_loyalty_points and can_redeem_via_package fields filled out.

Service Children

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/service/children"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_id":1111,
    "operator_id": -1,
    "service_id":3333,
    "price": 15.00
  }'

Example Response:

{
    "success": true,
    "appointments": [
        {
            "can_redeem_via_package": false,
            "can_redeem_via_loyalty_points": false,
            "client_id": 1111,
            "appointment_id": -1,
            "company_id": 12345,
            "operator_id": -1,
            "pos_original_price": 10.00,
            "price": 7.50,
            "service": {
                "barcode": "",
                "category_id": 0,
                "name": "Haircut",
                "price": 10.00,
                "service_id": 3333
            },
            "resource_id": 0,
            "service_id": 3333,
            "tax_rate": 10
        },
        {
            "can_redeem_via_package": false,
            "can_redeem_via_loyalty_points": false,
            "client_id": 1111,
            "appointment_id": -1,
            "company_id": 12345,
            "operator_id": -1,
            "pos_original_price": 10.00,
            "price": 7.50,
            "service": {
                "barcode": "",
                "category_id": 0,
                "name": "Haircut",
                "price": 10.00,
                "service_id": 3333
            },
            "resource_id": 0,
            "service_id": 3333,
            "tax_rate": 10
        }
    ]
}

Returns the price, tax rate, category and name of the services included in the requested group service, and calculates the individual service pricing based on the requested group service price.

HTTP Request

POST /v1/pos/service/children

Request Data

Parameter Type Description
client_id integer required The ID of the client to add to the sale.
company_id integer The ID of the company using POS. If omitted, defaults to the logged in user's company ID. Dome users must specify a child location.
operator_id integer required The ID of the operator who performed the appointment. Send -1 for none if setting force_operator_at_sale is false.
price decimal The price of the group service, used to calculate the prices of the included appointments. If omitted, the default price of the group service will be used.
service_id integer required The ID of the service to add.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
appointments Appointment[] The group appointments to add to the sale, with pos_original_price (the original price of the service, ie. without being in a group), price (the price now that it is in this group service) and tax_rate fields filled out. If setting advanced_discounting is true, and the service price does not match the original service price (due to the group parent overriding the price and/or the group parent having a discount applied), then discount_type_id will be -1 indicating a System Discount.

Service Loyalty Redeem

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/service/loyalty_redeem"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "appointment_id":-1
    "client_id":1111,
    "service_id":3333
  }'

Example Response:

{
    "success": true
}

Redeems the service by spending the client's loyalty point balance.
These are automatically processed in a separate transaction, so the service should be removed from your POS screen once redeemed successfully.

HTTP Request

POST /v1/pos/service/loyalty_redeem

Request Data

Parameter Type Description
appointment_id integer required The ID of the appointment to redeem, if it already exists, or -1 for an unsaved item added at POS.
client_id integer required The ID of the client redeeming the service.
company_id integer The ID of the company using POS. If omitted, defaults to the logged in user's company ID. If the Dome redeems a service, it will be redeemed by the company of the requested client.
service_id integer The ID of the service to redeem. Required if the appointment_id is -1.
operator_id integer The ID of the operator who performed the service. Required if the appointment_id is -1.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
parent_appointment_id integer If the appointment was part of a group service, and parent_appointment_id in the request was set to -1 for an unsaved item added at POS, then the ID of the claimed appointment's newly created group parent appointment will be returned. If there were other child appointments for this group service, update your local copy's group parent with the new appointment_id and clear its temporary pos_id.

Service Package Redeem

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/service/package_redeem"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "appointment_id":-1
    "client_id":1111,
    "service_id":3333
  }'

Example Response:

{
    "success": true
}

Redeems the service from the client's unclaimed package services.
These are automatically processed in a separate transaction, so the service should be removed from your POS screen once redeemed successfully.

HTTP Request

POST /v1/pos/service/package_redeem

Request Data

Parameter Type Description
appointment_id integer required The ID of the appointment to redeem, if it already exists, or -1 for an unsaved item added at POS.
client_id integer required The ID of the client redeeming the service.
company_id integer The ID of the company using POS. If omitted, defaults to the logged in user's company ID. If the Dome redeems a service, it will be redeemed by the company of the requested client.
service_id integer The ID of the service to redeem. Required if the appointment_id is -1.
operator_id integer The ID of the operator who performed the service. Required if the appointment_id is -1.
parent_appointment_id integer The ID of the appointment's group parent appointment, or -1 for an unsaved item added at POS. Required if the appointment is part of a group service, omit if it's not part of a group service.
parent_service_id integer The ID of the group service. Required if the appointment is part of a group service, and parent_appointment_id is an unsaved item added at POS.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
parent_appointment_id integer If the appointment was part of a group service, and parent_appointment_id in the request was set to -1 for an unsaved item added at POS, then the ID of the claimed appointment's newly created group parent appointment will be returned. If there were other child appointments for this group service, update your local copy's group parent with the new appointment_id and clear its temporary pos_id.

Product Price Check

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/product/check"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_product_id": -1,
    "client_id":1111,
    "product_id":5555
  }'

Example Response:

{
    "success": true,
    "available_discounts": [
        {
            "amount": 10,
            "apply_automatically": false,
            "company_id": 12345,
            "discount_type": "%",
            "discount_type_id": 7171,
            "name": "10% off"
        },
        ...
    ]
    "client_product": {
        "can_redeem_via_package": true,
        "client_id": 1111,
        "client_product_id": -1,
        "company_id": 12345,
        "pos_original_price": 10.00,
        "price": 10.00,
        "product": {
            "brand": {
                "brand_id": 4444,
                "name": "Hair Products"
            },
            "brand_id": 4444,
            "name": "Shampoo",
            "product_id": 5555,
            "tax_free": false
        },
        "product_id": 5555,
        "quantity": 1,
        "tax_rate": 10
    }
}

Returns the price, tax rate, brand and name of the product, plus any auto-applied discount, and whether this client can redeem the product via an as yet unclaimed product from a previously purchased package.

HTTP Request

POST /v1/pos/product/check

Request Data

Parameter Type Description
barcode string The barcode of the product to add. Must specify either barcode or product_id.
client_id integer required The ID of the client to add to the sale.
client_product_id integer required The ID of the client product if it's an existing item. Send -1 for an item added at sale that is not yet saved to the server (see Special Values - Unsaved Item).
company_id integer The ID of the company using POS. If omitted, defaults to the logged in user's company ID. Dome users must specify a child location.
product_id integer The ID of the product to add. Must specify either barcode or product_id.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
available_discounts DiscountType[] The list of discount types that can be applied to this product. Omitted if setting advanced_discounting is false.
client_product ClientProduct The client product to add to the sale, with pos_original_price (the price before any auto-applied discount), tax_rate, discount_type_id (if a discount is automatically applied) and can_redeem_via_package fields filled out.

Product Package Redeem

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/product/package_redeem"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_id":1111,
    "product_id":5555,
    "quantity": 1
  }'

Example Response:

{
    "success": true
}

Redeems the product from the client's unclaimed package products.
These are automatically processed in a separate transaction, so the product should be removed from your POS screen once redeemed successfully.

HTTP Request

POST /v1/pos/product/package_redeem

Request Data

Parameter Type Description
client_id integer required The ID of the client redeeming the product.
company_id integer The ID of the company using POS. If omitted, defaults to the logged in user's company ID. If the Dome redeems a product, it will be redeemed by the company of the requested client.
product_id integer required The ID of the product to redeem.
quantity integer required The number of products to redeem.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).

Voucher Price Check

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/voucher/check"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_voucher_id": -1,
    "client_id":1111,
    "voucher_id":7777
  }'

Example Response:

{
    "success": true,
    "available_discounts": [
        {
            "amount": 10,
            "apply_automatically": false,
            "company_id": 12345,
            "discount_type": "%",
            "discount_type_id": 7171,
            "name": "10% off"
        },
        ...
    ]
    "client_voucher": {
        "client_id": 1111,
        "client_voucher_id": -1,
        "company_id": 12345,
        "pos_original_price": 10.00,
        "price": 10.00,
        "voucher": {
            "name": "$100 Gift Voucher",
            "voucher_id": 7777
        },
        "voucher_id": 7777,
        "tax_rate": 10
    }
}

Returns the price and name of the voucher, plus any auto-applied discount.

HTTP Request

POST /v1/pos/voucher/check

Request Data

Parameter Type Description
barcode string The barcode of the voucher to add. Must specify either barcode or voucher_id.
client_id integer required The ID of the client to add to the sale.
client_voucher_id integer required The ID of the client voucher if it's an existing item. Send -1 for an item added at sale that is not yet saved to the server (see Special Values - Unsaved Item).
company_id integer The ID of the company using POS. If omitted, defaults to the logged in user's company ID. Dome users must specify a child location.
voucher_id integer The ID of the voucher to add. Must specify either barcode or voucher_id.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
available_discounts DiscountType[] The list of discount types that can be applied to this voucher. Omitted if setting advanced_discounting is false.
client_voucher ClientVoucher The client voucher to add to the sale, with pos_original_price (the price before any auto-applied discount) and discount_type_id (if a discount is automatically applied) fields filled out.

Package Price Check

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/package/check"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_package_id": -1,
    "client_id":1111,
    "package_id":9999
  }'

Example Response:

{
    "success": true,
    "available_discounts": [
        {
            "amount": 10,
            "apply_automatically": false,
            "company_id": 12345,
            "discount_type": "%",
            "discount_type_id": 7171,
            "name": "10% off"
        },
        ...
    ]
    "client_package": {
        "client_id": 1111,
        "client_package_id": -1,
        "company_id": 12345,
        "pos_original_price": 10.00,
        "price": 10.00,
        "package": {
            "name": "10 x Haircut",
            "package_id": 9999,
            "tax_free": false
        },
        "package_id": 9999,
        "tax_rate": 10
    }
}

Returns the price, tax rate and name of the package, plus any auto-applied discount.

HTTP Request

POST /v1/pos/package/check

Request Data

Parameter Type Description
barcode string The barcode of the package to add. Must specify either barcode or package_id.
client_id integer required The ID of the client to add to the sale.
client_package_id integer required The ID of the client package if it's an existing item. Send -1 for an item added at sale that is not yet saved to the server (see Special Values - Unsaved Item).
company_id integer The ID of the company using POS. If omitted, defaults to the logged in user's company ID. Dome users must specify a child location.
package_id integer The ID of the package to add. Must specify either barcode or package_id.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
available_discounts DiscountType[] The list of discount types that can be applied to this package. Omitted if setting advanced_discounting is false.
client_package ClientPackage The client package to add to the sale, with pos_original_price (the price before any auto-applied discount), tax_rate and discount_type_id (if a discount is automatically applied) fields filled out.

Membership Price Check

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/membership/check"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_membership_id": -1,
    "client_id":1111,
    "membership_id":4647
  }'

Example Response:

{
    "success": true,
    "available_discounts": [
        {
            "amount": 10,
            "apply_automatically": false,
            "company_id": 12345,
            "discount_type": "%",
            "discount_type_id": 7171,
            "name": "10% off"
        },
        ...
    ]
    "client_membership": {
        "client_id": 1111,
        "client_membership_id": -1,
        "company_id": 12345,
        "pos_original_price": 10.00,
        "price": 10.00,
        "membership": {
            "membership_id": 4647,
            "name": "Monthly Membership",
            "payment_type": "recurring",
            "recurring_fee": 14.99,
            "recurring_type": "monthly",
            "tax_free": false
        },
        "membership_id": 4647,
        "tax_rate": 10
    }
}

Returns the initial setup price, tax rate, payment type, name and any recurring details of the membership, plus any auto-applied discount.

HTTP Request

POST /v1/pos/membership/check

Request Data

Parameter Type Description
client_id integer required The ID of the client to add to the sale.
client_membership_id integer required The ID of the client membership if it's an existing item. Send -1 for an item added at sale that is not yet saved to the server (see Special Values - Unsaved Item).
company_id integer The ID of the company using POS. If omitted, defaults to the logged in user's company ID. Dome users must specify a child location.
membership_id integer required The ID of the membership to add.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
available_discounts DiscountType[] The list of discount types that can be applied to this membership. Omitted if setting advanced_discounting is false.
client_membership ClientMembership The client membership to add to the sale, with pos_original_price (the price before any auto-applied discount), tax_rate and discount_type_id (if a discount is automatically applied) fields filled out.

Special Values

Unsaved Item

A value of -1 in a POS item's id (appointment_id, client_product_id, clientvoucher_id, client_package_id, client_membership_id) indicates that the item has been added to a local POS screen, but has not yet been saved to the server.

Transactions

Add

Example Request:

curl "https://apiN.simplesalon.com/v1/transaction/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "appointments": [
        {
            "client_id": 1111,
            "appointment_id": -1,
            "operator_id": -1,
            "pos_id": "myref1",
            "price": 10.03,
            "service_id": 3333
        }
    ],
    "client_memberships": [],
    "client_packages": [],
    "client_products": [],
    "client_vouchers": [],
    "transaction_type": "sale"
  }'

Example Response:

{
    "success": true,
    "transaction": {
        "transaction_id": 85735,
        "amount": 10.03,
        "status": "incomplete"
    }
    "transaction_id": 85735,
    "appointments": [
        {
            "appointment_id": 56793,
            "client_id": 1111,
            "company_id": 12345,
            "duration": 15,
            "operator_id": 2222,
            "pos_id": "myref1",
            "resource_id": 0,
            "service": {
                "category": {
                    "category_id": 0,
                    "name": "No Category"
                },
                "category_id": 0,
                "name": "Haircut",
                "service_id": 3333
            },
            "service_id": 3333,
            "time_end": "2019-01-01T11:15:00+11:00",
            "time_start": "2019-01-01T11:00:00+11:00",
            "transaction_id": 85735
        }
    ],
    "client_memberships": [],
    "client_packages": [],
    "client_products": [],
    "client_vouchers": []
}

Adds a new transaction (as status = incomplete) and adds all the linked items to it.

Items that were unsaved should be sent with a unique pos_id value. If the transaction is successfully added, they will be assigned an item ID from the server - you will need to update your local list with the new ID, and clear the temporary pos_id reference.
Items that were unsaved and were part of a group service should also have a parent_pos_id value which matches the pos_id of the unsaved parent service. This should also be cleared when an item ID is assigned by the server.

HTTP Request

POST /v1/transaction/add

Request Data

Parameter Type Description
account_values AccountValue[] The list of account values to add to the sale.
Must specify account_value_id, client_id and price.
appointments Appointment[] The list of appointments to add to the sale.
Must specify appointment_id, client_id, operator_id, service_id, price (price is not needed for group parents).
client_packages ClientPackage[] The list of client packages to add to the sale.
Must specify client_package_id, client_id, operator_id, package_id, price.
client_products ClientProduct[] The list of client products to add to the sale.
Must specify client_product_id, client_id, operator_id, product_id, price, quantity.
client_vouchers ClientVoucher[] The list of client vouchers to add to the sale.
Must specify client_voucher_id, client_id, operator_id, voucher_id, price.
client_memberships ClientMembership[] The list of client memberships to add to the sale.
Must specify client_membership_id, client_id, operator_id, membership_id, price, start_date.
company_id integer The ID of the company using POS. If omitted, defaults to the logged in user's company ID. Dome users must specify a child location.
linked_transaction_id integer The ID of the original transaction, for example, if you are performing a linked refund of an existing sale.
tips Tip[] The list of tips to add to the sale.
Must specify tip_id, operator_id and price.
transaction_type string required The type of transaction to add. Valid values are sale and refund.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
account_values AccountValue[]
appointments Appointment[] The list of appointments added to the sale.
client_packages ClientPackage[] The list of client packages added to the sale.
client_products ClientProduct[] The list of client products added to the sale.
client_vouchers ClientVoucher[] The list of client vouchers added to the sale.
client_memberships ClientMembership[] The list of client memberships added to the sale.
tips Tip[]
transaction_id integer The ID of the new transaction.
transaction Transaction The new transaction.

Cancel

Example Request:

curl "https://apiN.simplesalon.com/v1/transaction/cancel"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "transaction_id": 85735
  }'

Example Response:

{
    "success": true
}

Cancels an incomplete transaction. You must have removed all payments first.

HTTP Request

POST /v1/transaction/cancel

Request Data

Parameter Type Description
transaction_id integer required The ID of the transaction to cancel.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).

Complete

Example Request:

curl "https://apiN.simplesalon.com/v1/transaction/complete"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "transaction_id": 85735
  }'

Example Response:

{
    "success": true,
    "notices": [
        {
            "loyalty_points": [
                {
                    "can_convert_to_gift_voucher": true,
                    "client_id": 1111,
                    "client_name": "Joe Citizen",
                    "loyalty_points": 437
                }
            ],
            "title": "Loyalty Points: (After Sale)",
            "type": "loyalty_points"
        }
    ]
}

Completes an incomplete transaction. You must have added all payments first, ie. amount_owing is between -0.02 and 0.02 (rounding will be calculated once the transaction completed).

HTTP Request

POST /v1/transaction/complete

Request Data

Parameter Type Description
transaction_id integer required The ID of the transaction to complete.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
notices TransactionCompleteNotice[] A list of notices to display to the user.

Add Payment

Example Request:

curl "https://apiN.simplesalon.com/v1/transaction/payment/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "payments": [
        {
            "payment_type_id": 1,
            "pos_id": "myref1",
            "amount": 10.10,
            "extra_fields": [
                {
                    "extra_field":"change",
                    "value":"0.07"
                }
            ]
        }
    ],
    "transaction_id": 85735
  }'

Example Response:

{
    "payments": [
        {
            "payment_id": 6672,
            "payment_type_id": 1,
            "pos_id": "myref1",
            "amount": 10.00,
            "extra_fields": [
                {
                    "extra_field": "change",
                    "value": "0.07"
                }
            ],
        }
    ]
    "success": true,
    "transaction": {
        "transaction_id": 85735,
        "amount": 10.03,
        "amount_owing": -0.02,
        "amount_paid": 10.05,
        "payments": [
            {
                "amount": 10.05,
                "payment_id": 6672,
                "payment_type_id": 1,
                "transaction_id": 85735
            }
        ],
        "status": "incomplete"
    }
    "transaction_id": 85735,
}

Adds new payments to an incomplete transaction.

Payments should be sent with a unique pos_id value. If the payment is successfully added, they will be assigned a payment_id from the server - you will need to update your local payment list with the new ID, and clear the temporary pos_id reference.

HTTP Request

POST /v1/transaction/payment/add

Request Data

Parameter Type Description
payments Payment[] required The list of payments to add to the sale.
Must specify payment_type_id and amount.
transaction_id integer required The ID of the transaction to add payments to.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
payments Payment[] The list of payments added to the sale in this call (the full list is available under the transaction object).
transaction Transaction The transaction.
transaction_id integer The ID of the transaction.

Process Live Payment

Example Request:

curl "https://apiN.simplesalon.com/v1/transaction/payment/process"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "gateway": "giftvoucher",
    "barcode": "900000000123",
    "extra_fields": [],
    "transaction_id": 85735
  }'

Example Response:

{
    "amount": 10.00,
    "extra_fields": [
        {
            "extra_field": "change",
            "value": "0.07"
        }
    ],
    "success": true
}

Processes a live payment on an incomplete transaction.

If successful, and a payment_id is returned, add the successful payment to your list of payments displayed for this transaction.
If successful, and a payment_id is not returned, you must process the payment yourself via the Add Payment call. For example, the Gift Voucher live payment method will only return the type and total amount of the client voucher that can be claimed, and you can then choose how much of the amount to use for a cash-type voucher.

HTTP Request

POST /v1/transaction/payment/process

Request Data

Parameter Type Description
amount decimal The amount of the payment.
barcode string The barcode relating to the payment (eg. a gift voucher barcode to lookup, or the client's Afterpay barcode)
extra_fields ExtraField[] The extra fields required by this live payment type.
gateway string required The gateway to use to process this payment.
step integer The step number for live payments that require multiple steps to complete.
transaction_id integer required The ID of the transaction this payment is linked to.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
amount decimal The amount of the payment (this may have changed from the request, for example, if an item voucher is used, the response amount will be set to the price of the item claimed).
payment Payment[] The payment added to the sale in this call. Only included if the payment has been automatically processed.
payment_id integer The ID of the completed payment. Only included if the payment has been automatically processed.
transaction Transaction The transaction. Only included if the payment has been automatically processed.
transaction_id integer The ID of the transaction. Only included if the payment has been automatically processed.
extra_fields ExtraField[] The extra fields returned by this live payment type.

Delete Payment

Example Request:

curl "https://apiN.simplesalon.com/v1/transaction/payment/delete"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "payment_id": 6672
  }'

Example Response:

{
    "success": true
}

Deletes a payment from an incomplete transaction.

HTTP Request

POST /v1/transaction/payment/delete

Request Data

Parameter Type Description
payment_id integer required The ID of the payment to delete

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).

Models

Transaction

Parameter Type Description
amount decimal The total amount of the transaction.
amount_owing decimal The total amount of the transaction minus the amount_paid. Only set for an incomplete transaction.
amount_paid decimal The total amount of payments for the transaction. Only set for an incomplete transaction.
company_id integer The company ID of the transaction.
linked_transaction_id integer The ID of the original transaction for a linked refund of an existing sale.
payments Payment[]
status string The status of the transaction. Valid values are complete and incomplete.
transaction_id integer The ID of the transaction.

Payment

Parameter Type Description
amount decimal The amount of the payment.
extra_fields ExtraField[] The extra fields required by this payment type (used for Live Payment types).
transaction_id integer The ID of the transaction this payment is linked to.
payment_id integer The ID of the payment.
payment_type_id integer The ID of the Payment Type.
pos_id string Your unique identifier for an unsaved payment. Only used in the Add Payment API call.

Account Value

Parameter Type Description
account_value_id integer The ID of the account value adjustment.
client_id integer The ID of the client to add account value to.
pos_id string Your unique identifier for an unsaved account value. Only used in the Add Transaction API call.
price decimal The amount of account value to add.

Tip

Parameter Type Description
tip_id integer The ID of the tip.
operator_id integer The ID of the operator who received the tip.
pos_id string Your unique identifier for an unsaved tip. Only used in the Add Transaction API call.
price decimal The amount of the tip.

TransactionCompleteNotice

Parameter Type Description
type string The type of notice, to identify which extra fields will be set. Valid values are basic (no extra fields set), loyalty_points, gift_voucher, print.
title string The title of the message to display.
message string The content of the message to display. May be omitted for non-basic message types.
gift_voucher TransactionCompleteNotice - GiftVoucher[] Extra data for a gift_voucher type notice.
loyalty_points TransactionCompleteNotice - LoyaltyPoints[] Extra data for a loyalty_points type notice.
print TransactionCompleteNotice - Print[] Extra data for a print type notice.

TransactionCompleteNotice - GiftVoucher

Parameter Type Description
barcode integer The barcode of the client voucher.
client_id integer The ID of the client the client voucher is assigned to.
client_name string The name of the client the client voucher is assigned to.
gift_voucher_id integer The ID of the gift voucher.
gift_voucher_name string The name of the gift voucher.
expiry_date string The expiry date of the client voucher. Omitted if the client voucher never expires.

TransactionCompleteNotice - LoyaltyPoints

Parameter Type Description
client_id integer The ID of the client.
client_name string The name of the client.
loyalty_points integer The number of loyalty points this client has.
can_convert_to_gift_voucher boolean true when the client has enough loyalty points to convert them to a gift voucher, false if the client doesn't have enough points.

TransactionCompleteNotice - Print

Parameter Type Description
title string The title of the notice to print.
html string The content of the notice to print.

Errors

Example Response:

{
  "success": false,
  "error":
  {
    "code": "INVALIDTOKEN",
    "message": "Login token is invalid or has expired"
  },
}

When an error occurs, success will be set to false, and the response will have the error field set.

Parameter Type Description
success boolean Always false when an error occurs.
error Message The error message details.

Dates

Format

Dates should be passed (and will be returned) in ISO 8601 format, for example 2019-01-22T00:00:00+11:00 is midnight in 'AUS Eastern Standard Time' (Melbourne, during daylight saving months).

When requesting a range, the time_start is inclusive, and time_end is exclusive, so 2019-01-22T00:00:00+11:00 to 2019-01-23T00:00:00+11:00 gives you all results on the 22nd Jan 2019, which would include a result at midnight on the 22nd Jan, but would not include a result at midnight on 23rd Jan.

Timezones

Dates are returned in the timezone of the company they belong to. For example if your company is in Victoria, but you are in a Dome with a company from South Australia, any results you get from the South Australian company will be in Cen. Australia Standard Time. The offset part of the date (ie. +10:30) identifies the timezone used.

You can check the timezone of the company by requesting the timezone setting. Timezone result will be an option from the Microsoft Default Timezones list. You can alternatively check the timezone_iana setting - this value will be converted directly from the timezone value to the best-fit IANA timezone value.

Models

ExtraField

Example:

{
  "extra_field": "change",
  "value": "0"
}
Parameter Type Description
extra_field string The extra field key.
value string The value of the extra field.

ListOptions

Example Request:

curl "https://apiN.simplesalon.com/v1/appointment/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        ...
    },
    "options":
    {
        "page_number": 1,
        "rows_per_page": 10,
        "return_total": false
    }
  }'
Parameter Type Description
page_number integer The page number of results to return. Defaults to page 1.
return_total boolean If true, the total number of rows matching your filters will be returned in the total_rows field in the result. Defaults to false.
rows_per_page string The number of rows per page. Defaults to 10 rows. Maximum 25 rows per page. There are some select methods (noted under their options parameter description) that allow -1 to retrieve all rows.

Message

Example Response:

{
  "success": false,
  "error":
  {
    "code": "INVALIDTOKEN",
    "message": "Login token is invalid or has expired"
  },
}
Parameter Type Description
code string The code associated with the message.
message string The human-readable message.
details string[] Any extra details relating to the message, for example, the name of the parameter for a Missing Parameter error.

Misc

Rate Limiting

Example Response:

{
    "success": false,
    "error": {
        "code": "IPRATELIMITED",
        "message": "Your IP address has had too many attempts to access the API in a short amount of time. Please try again later."
    }
}

Rate limiting applies to most requests - the Version and Logout calls are the exceptions.

A rate limit per IP address is applied to all Login requests.

A rate limit per Partner is applied to all other requests. If you have a need for your Partner rate limit to be increased, please contact us with details of your use case.

Support

Please visit https://help.simplesalon.com to view help articles, or submit a ticket with any questions.

Change Log

Version Changes
1.1.0 Added POS and Transaction functionality.
Added Appointment Add and Add Search functionality.
1.0.0 Initial release