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

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.0000000",
            "time_start": "2019-01-01T10:45:00.0000000"
        }
    ]
}

Get a list of appointments between a date range.

Note: Results are normally restricted by the ListOptions rows_per_page limit. However for requesting the appointment page listing (ie. a single day's appointments, with show_visit: true), you can set rows_per_page: -1 to return all booked appointments for that day.

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.0000000",
        "time_start": "2019-01-01T10:45:00.0000000"
    }
}

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.

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.0000000"
    }
  }'

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.0000000",
        "time_start": "2019-01-01T11:00:00.0000000"
    }
}

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.

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.
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.
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.
client_id integer The client ID of the appointments.
company_id integer The company ID of the appointment.
duration integer The duration of the appointment, in minutes.
operator_id integer The operator ID 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.
time_end string The end time of appointment.
time_start string The start time of the appointment.

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 false, or omitted, does not include the Other state.

State

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

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.

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

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.

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.
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 inbetween 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.
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
company_id integer The company ID to retrieve services 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.
category_id integer The category ID to filter by. 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.

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.

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.

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

Packages

List

Example Request:

curl "https://apiN.simplesalon.com/v1/package/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "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
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.

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.

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.

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

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.

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.

Models

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.

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.

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.0.0 Initial release