NAV
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",
  "operator": [
    "company_id": 12345,
    "display_name": "",
    "firstname": "My",
    "lastname": "Username",
    "role_id": -1,
    "username": "myusername"
  ],
  "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 Your Company Token generated for the company who is logging in.
X-Partner-Token Your Partner Token provided by Simple Salon.

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.
operator Operator Details about the user who has logged in - only select Operator fields are included.
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.

Switch User

Example Request:

curl "https://apiN.simplesalon.com/v1/switch"
  -H 'Content-Type: application/json' \
  -H 'User-Agent: MyWebsite 1.0' \
  -d '
  {
    "token":"abcdef",
    "pin": 4567
  }'

Example Response:

{
  "success": true,
  "api_url": "https://api1.simplesalon.com",
  "expiry": "2019-01-01T00:00:00+00:00",
  "operator": [
    "company_id": 12345,
    "display_name": "Ash",
    "firstname": "Ashley",
    "lastname": "Smith",
    "role_id": -2,
    "username": ""
  ],
  "token": "mnopqr"
}

Use your existing login token to switch to a different user in the same company via PIN code. This will 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/switch

HTTP Headers

Header Value
Content-Type Always application/json
User-Agent A description of the software and version you are using

Request Data

Parameter Type Description
token string required Your Simple Salon API login token
pin integer required The quick login pin of the operator to switch to.

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.
operator Operator Details about the user who has logged in - only select Operator fields are included.
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).

Account

This retrieves account data from the Simple Salon account. An Administrator user will generally be required to call these functions.

Billing Invoice Get

Example Request:

curl "https://apiN.simplesalon.com/v1/account/billing/invoice/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "billing_invoice_id": 882277
  }'

Example Response:

{
    "success": true,
    "billing_invoice":
    {
        "amount": 50.00,
        "billing_invoice_id": 882277,
        "company_id": 12345,
        "currency_code": "AUD",
        "date": "2019-01-01T09:00:00+11:00",
        "external_id": "in_1LmWdsBcHHwD1IfWxU05WwwS",
        "external_link": "",
        "gateway": "stripe",
        "invoice_id": "1234567Y-0002",
        "status": "success",
        "total_amount": 55.00,
        "type": "smstopup_manual"
    }
}

Get an invoice.

HTTP Request

POST /v1/account/billing/invoice/get

Request Data

Parameter Type Description
billing_invoice_id integer required The ID of the billing invoice to retrieve.
generate_link boolean If true, the external_link will be generated for this billing invoice. Generating an external_link requires an external server call, and the link will be a timed access link, so don't set this option to true unless you specifically need the external_link. If omitted, defaults to false.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
billing_invoice BillingInvoice The billing invoice.

Billing Invoice List

Example Request:

curl "https://apiN.simplesalon.com/v1/account/billing/invoice/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        "for_company_id": 12345,
        "status": "success"
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "billing_invoices": [
        {
            "amount": 50.00,
            "billing_invoice_id": 882277,
            "company_id": 12345,
            "currency_code": "AUD",
            "date": "2019-01-01T09:00:00+11:00",
            "external_id": "in_1LmWdsBcHHwD1IfWxU05WwwS",
            "external_link": "",
            "gateway": "stripe",
            "invoice_id": "1234567Y-0002",
            "status": "success",
            "total_amount": 55.00,
            "type": "smstopup_manual"
        }
    ]
}

Get a list of invoices.

HTTP Request

POST /v1/account/billing/invoice/list

Request Data

Parameter Type Description
filters BillingInvoiceFilter required The filters to apply to the billing invoice list

Response Data

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

Billing Item Add

Example Request:

curl "https://apiN.simplesalon.com/v1/account/billing/item/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "billing_item":
    {
        "bill_at_dome": false,
        "company_id": 12345,
        "included_in_plan": false,
        "quantity": 1,
        "type": "adla"
    }
  }'

Example Response:

{
    "success": true,
    "billing_item":
    {
        "bill_at_dome": false,
        "billing_item_id": 3425422,
        "company_id": 12345,
        "included_in_plan": false,
        "quantity": 1,
        "type": "adla"
    }
}

Add a billing item.
Note that if skip_billing_refresh is omitted or false and the subscription update fails, the billing item will not be added and an error will be returned.

HTTP Request

POST /v1/account/billing/item/add

Request Data

Parameter Type Description
billing_item BillingItem required The billing item to add.
skip_billing_refresh boolean If true, the company's subscription will not be refreshed straightaway - you will need to manually perform the refresh. This should only be true when you are making several billing item updates - after the last update completes, call billing refresh to push all changes to the company's billing subscription. You may also need to manually refresh the Dome's billing subscription if you have adjusted any bill_at_dome values. If omitted, defaults to false.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
billing_item BillingItem The new billing item.

Billing Item Update

Example Request:

curl "https://apiN.simplesalon.com/v1/account/billing/item/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "billing_item":
    {
        "company_id": 12345,
        "type": "plan",
        "value": "pro"
    }
  }'

Example Response:

{
    "success": true,
    "billing_item":
    {
        "bill_at_dome": false,
        "billing_item_id": 3425423,
        "company_id": 12345,
        "included_in_plan": false,
        "quantity": 1,
        "type": "plan",
        "value": "pro"
    }
}

Updates a billing item.
Note that if skip_billing_refresh is omitted or false and the subscription update fails, the billing item will not be added and an error will be returned.

HTTP Request

POST /v1/account/billing/item/update

Request Data

Parameter Type Description
billing_item BillingItem required The billing item to update. You must specify billing_item_id, or a type of either plan or adla (to automatically update the billing item for this company of that type).
skip_billing_refresh boolean If true, the company's subscription will not be refreshed straightaway - you will need to manually perform the refresh. This should only be true when you are making several billing item updates - after the last update completes, call billing refresh to push all changes to the company's billing subscription. You may also need to manually refresh the Dome's billing subscription if you have adjusted any bill_at_dome values. If omitted, defaults to false.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
billing_item BillingItem The new billing item.

Billing Item Delete

Example Request:

curl "https://apiN.simplesalon.com/v1/account/billing/item/delete"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "billing_item_id": 3425422
  }'

Example Response:

{
    "success": true
}

Deletes a billing item.
Note that if skip_billing_refresh is omitted or false and the subscription update fails, the billing item will not be added and an error will be returned.

HTTP Request

POST /v1/account/billing/item/delete

Request Data

Parameter Type Description
billing_item_id integer required The ID of the billing item to delete
skip_billing_refresh boolean If true, the company's subscription will not be refreshed straightaway - you will need to manually perform the refresh. This should only be true when you are making several billing item updates - after the last update completes, call billing refresh to push all changes to the company's billing subscription. You may also need to manually refresh the Dome's billing subscription if you have adjusted any bill_at_dome values. If omitted, defaults to false.

Response Data

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

Billing Item Get

Example Request:

curl "https://apiN.simplesalon.com/v1/account/billing/item/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "billing_item_id": 3425423
  }'

Example Response:

{
    "success": true,
    "billing_item":
    {
        "bill_at_dome": false,
        "billing_item_id": 3425423,
        "company_id": 12345,
        "included_in_plan": false,
        "quantity": 1,
        "type": "plan",
        "value": "starter"
    }
}

Get a billing item.

HTTP Request

POST /v1/account/billing/item/get

Request Data

Parameter Type Description
billing_item_id integer required The ID of the billing item to retrieve.
expanded_fields ExpandedField[] Available fields for expanding are: billing_product.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
billing_item BillingItem The billing item.

Billing Item List

Example Request:

curl "https://apiN.simplesalon.com/v1/account/billing/item/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        "company_id": 12345,
        "type": "plan"
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "billing_items": [
        {
            "bill_at_dome": false,
            "billing_item_id": 3425423,
            "company_id": 12345,
            "included_in_plan": false,
            "quantity": 1,
            "type": "plan",
            "value": "starter"
        }
    ]
}

Get a list of billing items.

HTTP Request

POST /v1/account/billing/item/list

Request Data

Parameter Type Description
filters BillingItemFilter required The filters to apply to the billing item list
options ListOptions The options for list results.
options.expanded_fields ExpandedField[] Available fields for expanding are: billing_product.

Response Data

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

Example Request:

curl "https://apiN.simplesalon.com/v1/account/billing/link/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "company_id": 12345
  }'

Example Response:

{
    "success": true,
    "url": "https://billing.simplesalon.com/session/JUHhjkGFEEJjh"
}

Returns a billing portal URL to redirect the user to, for updating their payment details or changing their company's plan.

POST /v1/account/billing/link/get

Parameter Type Description
company_id integer required The ID of the company to get the billing portal link for. Defaults to the logged in user's company ID.
return_url string The URL to return the user to once they have finished in the billing portal. If omitted, defaults to the Simple Salon login page.
Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
url string The URL to redirect the user to.

Billing Product List

Example Request:

curl "https://apiN.simplesalon.com/v1/account/billing/product/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
      "company_id": 12345,
      "type": "plan"
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "billing_products": [
        {
            "billing_inclusions": [],
            "currency_code": "AUD",
            "name": "Starter",
            "per_operator": true,
            "product_code": "starter",
            "credit_price": 0.50,
            "type": "plan"
        },
        {
            "billing_inclusions": [
                {
                    "per_operator": true,
                    "quantity": 50,
                    "type": "sms"
                }
            ],
            "currency_code": "AUD",
            "name": "Plus",
            "per_operator": true,
            "product_code": "plus",
            "credit_price": 0.45,
            "type": "plan"
        },
        ...
    ]
}

Get a list of billing products.

HTTP Request

POST /v1/account/billing/product/list

Request Data

Parameter Type Description
filters BillingProductFilter required The filters to apply to the billing product 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).
billing_products BillingProduct[] The list of billing products matching the filters.

Billing Refresh

Example Request:

curl "https://apiN.simplesalon.com/v1/account/billing/refresh"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "company_id": 12345
  }'

Example Response:

{
    "success": true
}

Updates the company's billing subscription. This may trigger a pro-rata charge for any changes.

HTTP Request

POST /v1/account/billing/refresh

Request Data

Parameter Type Description
company_id integer required The ID of the company to refresh billing for. Defaults to the logged in user's company ID.

Response Data

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

Billing Signup

Example Request:

curl "https://apiN.simplesalon.com/v1/account/billing/signup"
  -H 'X-Partner-Token: PartnerToken' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "billing_items": [
        {
            "quantity": 1,
            "type": "plan",
            "value": "starter"
        }
    ],
    "verification_token": "weuih435hretbfgn"
  }'

Example Response:

{
    "success": true,
    "configuration_required": true,
    "url": "https://checkout.stripe.com/c/pay/cs_live_b1GR4KjXfKUdHh0Myeb9a1JU0e6WP0kof2WBJulnvm4PcGSc2QMg29ALlM#fidkdWxOYHwnPyd1blpxYHZxWnNpTRAfScpJ2N3amhWYHdzYHcnPPydocmBtamlhYHd2Jz9xd3BgeCUl"
}

Signup a new company.
This request does not require a user Authorization token for a brand new signup - the Partner Token header is required instead.

HTTP Request

POST /v1/account/billing/signup

Request Data

Parameter Type Description
billing_items BillingItem[] required The URL to return the user to once they have finished in the billing portal. If omitted, defaults to the Simple Salon login page.
verification_token string required The CAPTCHA response token.
cancel_url string The URL to return to if the signup is cancelled before completion.
dome boolean Set to true if the company is a Dome parent company. Defaults to false.
dome_company_id integer The Dome to add the new account to. If specified, an Authorization token for a user in that Dome company is required. Ignored if dome is true.
email string The email address for the new account.
promo_code string A promotion code.
referral_code string A referral code (if referred from another account).
step integer The signup step. If omitted, defaults to 1.
server_id integer The server to add the new account to. Ignored if dome_company_id is specified (child locations must be on the same server as their parent Dome).
success_url string The URL to return to when the signup is complete.
third_party_data string The third party data for signups directly from third parties.
third_party_redirect_url string The third party URL to redirect to after a successful signup, for signups directly from third parties
user_agent string The user's browser user agent string.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
configuration_required boolean If true, then a signup has been started, however more configuration is required before it can be used, eg. visiting the url to enter payment information.
url string The URL to redirect the user to for completing the signup (when configuration_required is true).

Billing Source List

Example Request:

curl "https://apiN.simplesalon.com/v1/account/billing/source/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        "type": "credit_card"
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "billing_sources": [
        {
            "account_number": "xxxx4242",
            "account_type": "visa",
            "company_id": 12345,
            "external_id": "card_1LjuCyBciFSC279T3522yyZW",
            "type": "credit_card"
        }
    ]
}

Get a list of payment sources attached to the account.
Currently returns all results (no paging).

HTTP Request

POST /v1/account/billing/source/list

Request Data

Parameter Type Description
filters BillingSourceFilter required The filters to apply to the billing source list

Response Data

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

SMS Balance

Example Request:

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

Example Response:

{
    "success": true,
    "balance": {
        "company_id": 12345,
        "credit_price": 0.25,
        "currency_code": "AUD",
        "currency_symbol": "$",
        "free_credits": 14,
        "funds": 20.48,
        "settings": [
            {
                "name": "sms_dedicated_number",
                "value": ""
            },
            {
                "name": "sms_gateway",
                "value": "smssimplesalon"
            },
            {
                "name": "sms_gateway_use_dome",
                "value": "0"
            },
            {
                "name": "allow_multiple_sms",
                "value": "1"
            },
            {
                "name": "allow_staff_to_sms",
                "value": "1"
            },
            {
                "name": "sms_autotopup_enabled",
                "value": "1"
            },
            {
                "name": "sms_autotopup_amount",
                "value": "50"
            },
            {
                "name": "sms_autotopup_threshold",
                "value": "20"
            }
        ]
    }
}

Get the current SMS balance, with a list of SMS settings.

HTTP Request

POST /v1/account/sms/balance

Request Data

Parameter Type Description
company_id integer The company ID to request SMS balance data for.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
balance SMS Balance The SMS balance data.

SMS Purchase

Example Request:

curl "https://apiN.simplesalon.com/v1/account/sms/purchase"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "amount": 50.00
  }'

Example Response:

{
    "success": true,
    "balance": {
        "company_id": 12345,
        "currency_code": "AUD",
        "currency_symbol": "$",
        "free_credits": 14,
        "funds": 70.48,
        "settings": [
            {
                "name": "sms_dedicated_number",
                "value": ""
            },
            {
                "name": "sms_gateway",
                "value": "smssimplesalon"
            },
            {
                "name": "sms_gateway_use_dome",
                "value": "0"
            },
            {
                "name": "allow_multiple_sms",
                "value": "1"
            },
            {
                "name": "allow_staff_to_sms",
                "value": "1"
            },
            {
                "name": "sms_autotopup_enabled",
                "value": "1"
            },
            {
                "name": "sms_autotopup_amount",
                "value": "50"
            },
            {
                "name": "sms_autotopup_threshold",
                "value": "20"
            }
        ]
    },
    "billing_transaction_id": 56489,
    "sms_transaction_id": 978110
}

Purchases the specified amount of SMS credit, then returns the updated SMS balance.

HTTP Request

POST /v1/account/sms/purchase

Request Data

Parameter Type Description
amount decimal required The amount of credit to purchase. Note that a processing fee may be applied to the total amount charged.
billing_source_external_id string The billing gateway's ID of the billing source to use to process the topup. If omitted, defaults to the company's default billing source.
company_id integer The company ID to purchase SMS credit for.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
balance SMS Balance The SMS balance data.
billing_transaction_id integer The ID of the billing transaction generated for this purchase.
sms_transaction_id integer The ID of the SMS transaction generated for this purchase.

SMS Quote

Example Request:

curl "https://apiN.simplesalon.com/v1/account/sms/quote"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "amount": 50.00
  }'

Example Response:

{
    "success": true,
    "quote": {
        "amount": 50.00,
        "billing_source": {
            "account_number": "xxxx4242",
            "account_type": "visa",
            "company_id": 12345,
            "external_id": "card_1LjuCyBciFSC279T3522yyZW",
            "type": "credit_card"
        }
        "company_id": 12345,
        "currency_code": "AUD",
        "currency_symbol": "$",
        "total_amount": 55.00
    }
}

Returns the cost of purchasing the specified amount of credit - including any processing fee.

HTTP Request

POST /v1/account/sms/quote

Request Data

Parameter Type Description
amount decimal required The amount of credit to estimate purchasing.
billing_source_external_id string The billing gateway's ID of the billing source to use to estimate the topup amount. If omitted, defaults to the company's default billing source.
company_id integer The company ID to estimate purchasing SMS credit for.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
quote SMS Quote. The credit quote result.

SMS Transfer

Example Request:

curl "https://apiN.simplesalon.com/v1/account/sms/transfer"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "funds": 10.00
    "destination_company_id": 12346
  }'

Example Response:

{
    "success": true,
    "balance": {
        "company_id": 12345,
        "currency_code": "AUD",
        "currency_symbol": "$",
        "free_credits": 14,
        "funds": 60.48
    },
    "sms_transaction_id": 978110,
    "destination_balance": {
        "company_id": 12346,
        "currency_code": "AUD",
        "currency_symbol": "$",
        "free_credits": 0,
        "funds": 10.00
    }
}

Transfers the specified amount of SMS credit and/or funds from one company to another.
The destination company's SMS transaction ID is returned, along with the balances for both source and destination company.

HTTP Request

POST /v1/account/sms/transfer

Request Data

Parameter Type Description
destination_company_id integer required The company ID to transfer to.
funds decimal required* The amount of funds to transfer. If omitted, defaults to 0. Must specify either funds or free_credits.
free_credits integer required* The amount of credits to transfer. If omitted, defaults to 0. Must specify either funds or free_credits.
company_id integer The company ID to transfer from. If omitted, defaults to the logged in user's company ID.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
balance SMS Balance The updated SMS balance data for the source company. Note: settings are not included.
sms_transaction_id integer The ID of the SMS transaction generated for this transfer in the destination company.
destination_balance SMS Balance The updated SMS balance data for the destination company.

Models

Billing Inclusion

Parameter Type Description
quantity integer The amount of the item to include.
per_operator boolean If true, the billing inclusion quantity is applied for each operator in the company. If false, the billing inclusion quantity is applied once only, regardless of how many operators the company has.
type string The type of billing inclusion. Valid values are: sms (SMS credits).

Billing Invoice

Parameter Type Description
billing_invoice_id integer The internal invoice ID.
amount decimal The amount of the transaction (excluding transaction fees).
company_id integer The company ID that the invoice was charged to.
currency_code string The 3-letter ISO 4217 code of the currency of the amount and total_amount.
currency_symbol string The currency symbol of the currency of the amount and total_amount.
date string The date of the invoice. See Dates.
external_id string The ID of the invoice at the billing gateway.
external_link string The link to download the invoice. Note that the external_link may be blank - in this case you need to specifically request a (timed) link to be generated by setting generate_link=true for the Billing Invoice Get call.
for_company_id integer The company ID that the invoice was charged for. If omitted, the charge was for the company it was billed to (ie. company_id).
gateway string The billing gateway that the invoice was charged through.
invoice_id string The visible invoice ID.
status string The status of the invoice. Valid values are: success, failure.
total_amount decimal The total amount of the transaction (including any transaction fees).
type string The type of invoice. Valid values are: inclusion (an automatic plan inclusion invoice), smstopup_manual (an SMS topup manually performed by a user), smstopup_auto (an SMS topup automatically performed by the system when the SMS balance drops below the threshold), activation (a manual plan inclusion activation, for example, paying the plan fee to reactivate the account from On Hold), once_off (a single charge, for example, purchasing a data import).

BillingInvoiceFilter

Parameter Type Description
company_id integer The company ID that the invoice was charged to.
date_min string The invoice date to filter by (inclusive). See Dates.
date_max string The invoice date to filter by (exclusive). See Dates.
for_company_id integer The company ID that the invoice was charged for.
status string The status of the billing invoice. Valid values are: success, failure.
type string The type of billing invoice. See Billing Invoice type field for valid values.

Billing Item

Parameter Type Description
billing_item_id integer The billing item ID.
bill_at_dome boolean If true, the item is paid for by the company's Dome.
billing_active boolean If true, the item has been added to the company's subscription. If false, it has not yet been added (it will be added the next time the company's subscription is refreshed).
billing_product Billing Product The billing product. Must be specifically requested using expanded fields.
company_id integer The company ID that the billing item is for.
included_in_plan boolean If true, the billing item is included in the base plan (ie. it is free).
quantity integer The quantity of the billing item.
type string The type of billing item. Valid values are: plan (the base subscription plan), adla (an ADLA addon), sms_dedicated_number (a dedicated number for SMS addon).
value string The value of the billing item. For example, for a type=plan billing item, this field will contain the billing product's product_code.

BillingItemFilter

Parameter Type Description
company_id integer The company ID that the billing item is for.
billed_to_company_id integer The company ID that the billing item will be billed to.
type string The type of billing item. Valid values are: plan (the base subscription plan), adla (an ADLA addon), sms_dedicated_number (a dedicated number for SMS addon).

Billing Product

Parameter Type Description
product_code string The billing product code.
billing_inclusions Billing Inclusion[] The billing inclusions for this product. Only returned when type=plan.
currency_code string The 3-letter ISO 4217 code of the currency of the price and credit_price.
name string The name of the billing product.
per_operator boolean If true, the billing product price is applied for each operator in the company. If false, the billing product price is applied once only, regardless of how many operators the company has.
credit_price decimal The SMS price per credit. Only returned when type=plan.
type string The type of billing product. Valid values are: plan (the base subscription plan), adla (an ADLA addon), sms_dedicated_number (a dedicated number for SMS addon).
price decimal The price of the billing product.

BillingProductFilter

Parameter Type Description
company_id integer The company ID to return pricing and inclusions for. Specify either company_id or country_id to retrieve pricing and inclusions information.
country_id integer The country ID to return pricing and inclusions for. Specify either company_id or country_id to retrieve pricing and inclusions information.
type string The type of billing item. Valid values are: plan (the base subscription plan), adla (an ADLA addon), sms_dedicated_number (a dedicated number for SMS addon). If omitted, defaults to plan.

Billing Source

Parameter Type Description
account_number string The account number.
account_type string The account type (eg. visa).
company_id integer The company ID.
external_id string The ID of the billing source at the billing gateway.
type string The type of billing source. Valid values are: credit_card, direct_debit.

BillingSourceFilter

Parameter Type Description
company_id integer The company ID.
type string The type of billing source. Valid values are: credit_card, direct_debit.

SMS Balance

Parameter Type Description
company_id string The company ID.
credits integer The amount of paid credits (for SMS gateways that use credit amounts).
credit_price decimal The price of a single SMS credit (for SMS gateways that use credit amounts).
currency_code string The 3-letter ISO 4217 code of the currency of the funds.
currency_symbol string The currency symbol of the currency of the funds.
free_credits integer The amount of free credits (for SMS gateways that award free credits - these usually expire, so they will be used before any paid credit from credits or funds is used).
free_credit_expiry string The earliest date that free_credits expire. Omitted if there is no expiry. See Dates.
funds decimal The amount of paid credit (for SMS gateways that use dollar amounts).
settings Setting[] The list of settings specific to SMS.

SMS Quote

Parameter Type Description
amount decimal The amount of credit that will be added to the account for this topup.
billing_source BillingSource[] The billing source that will be used (either the billing source specified by billing_source_external_id, or the company's default billing source for SMS topups).
currency_code string The 3-letter ISO 4217 code of the currency of the amount and total_amount.
currency_symbol string The currency symbol of the currency of the amount and total_amount.
total_amount decimal The cost of purchasing this topup - includes any processing fee.

Accounting

This retrieves data from the third party accounting software linked to the Simple Salon account.

Account List

Example Request:

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

Example Response:

{
    "success": true,    
    "accounts": [
        {
            "account_id": "11111111-2222-3333-4444-555555555555",
            "name": "Sales",
            "third_party_type": "REVENUE",
            "type": "sales"
        },
        ...
    ]
}

Get a list of third party accounts.
Currently returns all results (no paging).

HTTP Request

POST /v1/third_party/accounting/account/list

Request Data

Parameter Type Description
filters AccountFilter required The filters to apply to the account list
options ListOptions The options for list results.
options.expanded_fields_grouped ExpandedField[] Available fields for expanding are: in_use_by.

Response Data

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

Account Get

Example Request:

curl "https://apiN.simplesalon.com/v1/third_party/accounting/account/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "account_id": "11111111-2222-3333-4444-555555555555"
  }'

Example Response:

{
    "success": true,
    "account": 
    {
        "account_id": "11111111-2222-3333-4444-555555555555",
        "name": "Sales",
        "third_party_type": "REVENUE",
        "type": "sales"
    }
}

Gets a single account.

HTTP Request

POST /v1/third_party/accounting/account/get

Request Data

Parameter Type Description
account_id integer required The ID of the account to retrieve
expanded_fields ExpandedField[] Available fields for expanding are: in_use_by.
gateway string The accounting gateway to use. If omitted, defaults to the company's default accounting gateway.

Response Data

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

Contact List

Example Request:

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

Example Response:

{
    "success": true,    
    "contacts": [
        {
            "contact_id": "11111111-2222-3333-4444-666666666666",
            "name": "Office Supplies Shop"
        },
        ...
    ]
}

Get a list of third party contacts.
Currently returns all results (no paging).

HTTP Request

POST /v1/third_party/accounting/contact/list

Request Data

Parameter Type Description
filters ContactFilter required The filters to apply to the contact list

Response Data

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

Contact Get

Example Request:

curl "https://apiN.simplesalon.com/v1/third_party/accounting/contact/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "contact_id": "11111111-2222-3333-4444-666666666666"
  }'

Example Response:

{
    "success": true,
    "contact": 
    {
        "contact_id": "11111111-2222-3333-4444-666666666666",
        "name": "Office Supplies Shop"
    }
}

Gets a single contact.

HTTP Request

POST /v1/third_party/accounting/contact/get

Request Data

Parameter Type Description
contact_id integer required The ID of the contact to retrieve
gateway string The accounting gateway to use. If omitted, defaults to the company's default accounting gateway.

Response Data

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

Invoice Add

Example Request:

curl "https://apiN.simplesalon.com/v1/third_party/accounting/invoice/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "session_id": 647515512
  }'

Example Response:

{
    "success": true,
    "invoice": 
    {
        "invoice_id": "11111111-2222-3333-4444-777777777777",
        "number": "INV-1023"
    }
}

Adds an End of Day session to the third party accounting software as an invoice.

HTTP Request

POST /v1/third_party/accounting/invoice/add

Request Data

Parameter Type Description
session_id integer required The ID of the End of Day session to send to the third party accounting software.
gateway string The accounting gateway to use. If omitted, defaults to the company's default accounting gateway.

Response Data

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

Models

Account

Parameter Type Description
account_id string The ID of the account in the third party.
code string The code of the account in the third party.
in_use_by string[] A list of places where the account is referenced in Simple Salon. Must specifically request this field via ExpandedFields.
name string The name of the account in the third party.
third_party_type string The type of account in the third party.
type string The generic account type. Valid values are sales, expenses, assets or liabilities. May be omitted, if the third party account type does not map to any generic account types.

AccountFilter

Parameter Type Description
company_id integer The company ID to retrieve accounts for. If omitted, defaults to the logged in user's company ID.
gateway string The accounting gateway to use. If omitted, defaults to the company's default accounting gateway.
codes string[] A list of third party account codes to filter by. If omitted, returns all.
third_party_types string[] A list of third party account types to filter by. If omitted, returns all.
types string[] A list of generic account types to filter by. If omitted, returns all.

Contact

Parameter Type Description
contact_id string The ID of the contact in the third party.
name string The name of the contact in the third party.

ContactFilter

Parameter Type Description
company_id integer The company ID to retrieve contacts for. If omitted, defaults to the logged in user's company ID.
gateway string The accounting gateway to use. If omitted, defaults to the company's default accounting gateway.

Invoice

Parameter Type Description
invoice_id string The ID of the newly added invoice in the third party.
number string The number of the newly added invoice in the third party.
warnings string[] Any warnings returned by the third party.

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 matching 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.
options.expanded_fields_grouped ExpandedField[] Available fields for expanding are: clients, operators, resources, services, packages.
options.rows_per_page integer Can be set to -1 to retrieve all matching appointments for the special cases listed above.
options.sort_expression string Available fields for sorting are: time_start (default)

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.
clients Client[] The list of clients matching the returned appointments. Must specifically request this field via options.expanded_fields_grouped.
operators Operator[] The list of operators matching the returned appointments. Must specifically request this field via options.expanded_fields_grouped.
packages Package[] The list of packages matching the returned appointments which were bought as part of a package (ie. client_package_id is set). Must specifically request this field via options.expanded_fields_grouped.
resources Resource[] The list of resources matching the returned appointments. Must specifically request this field via options.expanded_fields_grouped.
services Service[] The list of services matching the returned appointments. Must specifically request this field via options.expanded_fields_grouped.

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
expanded_fields ExpandedField[] Available fields for expanding are: client_package, discounts, service.

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"
                }
            ],
            "more_available": true
        },
        {
            "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"
                }
            ],
            "more_available": false
        }
    ]
}

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 5 timeslots (or 3 times the number of operators if greater) per company - to see more options, call again with time_start adjusted accordingly. Note that more results may be returned if other operators are available in the last timeslot, eg. if you have three operators, your maximum results returned is nine, so if only two are available on a particular day at 9am, you will get the 9:00am, 9:15am, 9:30am, 9:45am and 10:00am slots returned for both operators, making a total of 10 results.
If you search for an appointment with a Group Service, you can omit 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. Alternatively, if you would like to specify a different operator_id for each child appointment in a group, include the child appointments in the request and set the parent_pos_id on each child to match the group parent's 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.
time_start_max string The time to stop searching for more timeslots - maximum of 7 days after time_start. If omitted, defaults to the maximum. Timezone offset in this field is ignored. See Dates.
times string[] The time blocks to include in the search. Valid values are: now (appointments between now and 3 hours from now), morning (appointments before 12pm), lunchtime (appointments between 11am and 2pm), afternoon (appointments between 12pm and 5pm) and evening (appointments after 5pm). Multiple values can be specified. If omitted, includes all.
options.expanded_fields_grouped ExpandedField[] Available fields for expanding are: operators, resources, services.
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).
options AppointmentOption[] The list of available timeslot options.

Add Search Dates

Example Request:

curl "https://apiN.simplesalon.com/v1/appointment/add/search/dates"
  -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",
    "time_start_max": "2019-01-08T11:00:00+11:00"
    "times": ["morning", "lunchtime"]
  }'

Example Response:

{
    "success": true,
    "dates": [
        {
            "date": "2019-01-01T00:00:00+11:00",
            "times": ["morning", "lunchtime"]
        },
        {
            "date": "2019-01-02T00:00:00+11:00",
            "times": ["morning"]
        }
    ]
}

Given a set of appointments, checks each date for an available timeslot for those appointments to be booked in. The most common usage for this function would be to display available dates on a calendar. Searches up to a maximum of 7 days from the time_start.
If you search for an appointment with a Group Service, you can omit the child appointments. Alternatively, if you would like to specify a different operator_id for each child appointment in a group, include the child appointments in the request and set the parent_pos_id on each child to match the group parent's pos_id.

HTTP Request

POST /v1/appointment/add/search/dates

Request Data

Parameter Type Description
appointments Appointment[] required The appointments to search for an available timeslot for. Must specify service_id, can optionally specify operator_id (see Notes for Add Search Dates below). All other fields are ignored.
company_id integer If omitted, defaults to the logged in user's company ID. Cannot be run at the Dome level - send a child location company ID instead.
time_start string The time to start the search from. If omitted, defaults to the user's current time. Timezone offset in this field is ignored. See Dates.
time_start_max string The time to stop searching for more available dates - maximum of 7 days after time_start. If omitted, defaults to the maximum. Timezone offset in this field is ignored. See Dates.
times string[] The time blocks to include in the search. Valid values are: any (any appointment on the day), morning (appointments before 12pm), lunchtime (appointments between 11am and 2pm), afternoon (appointments between 12pm and 5pm) and evening (appointments after 5pm). Multiple values can be specified. If omitted, defaults to any.
Field Notes for Add Search Dates
operator_id If omitted, available dates for this service will be returned for any available operator.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
dates AppointmentDate[] The list of available dates.

Add Check

Example Request:

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

Example Response:

{
    "success": true
}

Example Response with a warning:

{
    "success": true,
    "warnings": [
        {
            "code": "APPTIGNORESPROCESSING",
            "details": [
                "Requested: 15",
                "Available: 0"
            ],
            "message": "This appointment can be placed in this timeslot, with processing time ignored."
        },
        {
            "code": "APPTRESIZED",
            "details": [
                "Requested: 30",
                "Available: 15"
            ],
            "message": "This appointment could be placed in this timeslot, if duration is reduced - check details field for reduced duration value."
        }
    ]
}

Checks if the new appointments can be added - that they are valid, and there is a timeslot available for them.

HTTP Request

POST /v1/appointment/add/check

Request Data

Parameter Type Description
appointments Appointment[] required The appointments to check. Must specify client_id, duration, operator_id, service_id, time_start.
ignore_processing_duration boolean If false, the add check will fail if the appointment does not have enough time for its processing_duration (when processing_duration_blocked=false). If omitted, defaults to true.
ignore_processing_duration_at_close boolean If false, the add check will fail if the appointment does not have enough time for its processing_duration at the end of the day (when processing_duration_blocked=false). This allows you to ignore processing time if it clashes with other appointments, but enforce it at the end of the day (or vice versa). If omitted, defaults to ignore_processing_duration.
ignore_processing_duration_blocked boolean If false, the add check will fail if the appointment does not have enough time for its processing_duration (when processing_duration_blocked=true). Only a user with a Manager level Role or higher can set this to true. If omitted, defaults to true for Manager level Roles or higher.
ignore_processing_duration_blocked_at_close boolean If false, the add check will fail if the appointment does not have enough time for its processing_duration at the end of the day (when processing_duration_blocked=true). This allows you to ignore blocked processing time if it clashes with other appointments, but enforce it at the end of the day (or vice versa). Only a user with a Manager level Role or higher can set this to true. If omitted, defaults to ignore_processing_duration_blocked.
ignore_other_processing_duration_blocked boolean If false, the add check will fail if the appointment is placed into another appointment's processing_duration_blocked time. Only a user with a Manager level Role or higher can set this to true. If omitted, defaults to false.

See Appointment Add for specific appointments field notes and requirements.

Response Data

Parameter Type Description
success boolean true if the appointment could be added, false if it cannot (see Errors).
warnings Message[] There may be warnings relating to adding this appointment - for example, a message that the appointment could be added in this timeslot if you ignore the appointment's processing time (see Common Errors and Warnings). If success is false, you will need to adjust the appointment according to all the warnings before calling Appointment Add. If success is true, the warnings will still be returned, but it will not prevent you from adding the appointment.

Common Errors and Warnings

See Appointment Add: Common Errors and Warnings.

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 (unless the existing appointment is a Class appointment).

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.
ignore_processing_duration boolean If false, the add will fail if the appointment does not have enough time for its processing_duration (when processing_duration_blocked=false). If omitted, defaults to true.
ignore_processing_duration_at_close boolean If false, the add will fail if the appointment does not have enough time for its processing_duration at the end of the day (when processing_duration_blocked=false). This allows you to ignore processing time if it clashes with other appointments, but enforce it at the end of the day (or vice versa). If omitted, defaults to ignore_processing_duration.
ignore_processing_duration_blocked boolean If false, the add will fail if the appointment does not have enough time for its processing_duration (when processing_duration_blocked=true). Only a user with a Manager level Role or higher can set this to true. If omitted, defaults to true for Manager level Roles or higher.
ignore_processing_duration_blocked_at_close boolean If false, the add will fail if the appointment does not have enough time for its processing_duration at the end of the day (when processing_duration_blocked=true). This allows you to ignore blocked processing time if it clashes with other appointments, but enforce it at the end of the day (or vice versa). Only a user with a Manager level Role or higher can set this to true. If omitted, defaults to ignore_processing_duration_blocked.
ignore_other_processing_duration_blocked boolean If false, the add will fail if the appointment is placed into another appointment's processing_duration_blocked time. Only a user with a Manager level Role or higher can set this to true. If omitted, defaults to false.
send_confirmation boolean If true, the client will receive a confirmation SMS and/or Email with their appointment time. If omitted, defaults to false.
appointments 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, unless the existing appointment is a Class appointment, in which case the client_id must not be the same as any other child appointments of 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.
redeem_via_membership If true, this appointment will be redeemed by claiming one of the client's membership inclusion items. If the client does not have any of this service to redeem, the call will fail.
redeem_via_package If true, this appointment will be redeemed by claiming one of the client's previously purchased (and as yet unclaimed) package items. If the client does not have any of this service to redeem, the call will fail.
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.
warnings Message[] There may be warnings relating to adding this appointment - for example, a message that the appointment could be added in this timeslot if you ignore the appointment's processing time (see Common Errors and Warnings). If success is false, you will need to adjust the appointment according to all the warnings before calling Appointment Add again. If success is true, the warnings will still be returned, but the appointment will have been added.

Common Errors and Warnings

Type Code Description
Warning APPTIGNORESPROCESSING This appointment could be placed in this timeslot, if processing time is ignored (set ignore_processing_duration=true)
Warning APPTIGNORESBLOCKEDPROCESSING This appointment could be placed in this timeslot, if blocked processing time is ignored (set ignore_processing_duration_blocked=true)
Warning APPTIGNORESOTHERBLOCKEDPROCESSING This appointment could be placed in this timeslot, if an earlier appointment's blocked processing time is ignored (set ignore_other_processing_duration_blocked=true).
Warning APPTRESIZED This appointment could be placed in this timeslot, if duration is reduced - check details field for reduced duration value.
Error APPOINTMENTSLOTUNAVAILABLE This appointment cannot fit in this timeslot. More details may be provided in the details field.

Update Check

Example Request:

curl "https://apiN.simplesalon.com/v1/appointment/update/check"
  -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
}

Checks if the appointment can be updated - that it is valid, and there is a timeslot available for it.

HTTP Request

POST /v1/appointment/update/check

Request Data

Parameter Type Description
appointment Appointment required The appointment to check. Must specify appointment_id. Omitted or null fields are left unchanged.
ignore_processing_duration boolean If false, the update check will fail if the appointment does not have enough time for its processing_duration (when processing_duration_blocked=false). If omitted, defaults to true.
ignore_processing_duration_at_close boolean If false, the update check will fail if the appointment does not have enough time for its processing_duration at the end of the day (when processing_duration_blocked=false). This allows you to ignore processing time if it clashes with other appointments, but enforce it at the end of the day (or vice versa). If omitted, defaults to ignore_processing_duration.
ignore_processing_duration_blocked boolean If false, the update check will fail if the appointment does not have enough time for its processing_duration (when processing_duration_blocked=true). Only a user with a Manager level Role or higher can set this to true. If omitted, defaults to true for Manager level Roles or higher.
ignore_processing_duration_blocked_at_close boolean If false, the update check will fail if the appointment does not have enough time for its processing_duration at the end of the day (when processing_duration_blocked=true). This allows you to ignore blocked processing time if it clashes with other appointments, but enforce it at the end of the day (or vice versa). Only a user with a Manager level Role or higher can set this to true. If omitted, defaults to ignore_processing_duration_blocked.
ignore_other_processing_duration_blocked boolean If false, the update check will fail if the appointment is placed into another appointment's processing_duration_blocked time. Only a user with a Manager level Role or higher can set this to true. If omitted, defaults to false.

See Appointment Update for specific appointments field notes and requirements.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
warnings Message[] There may be warnings relating to updating this appointment - for example, a message that the appointment could be moved to this timeslot if you ignore the appointment's processing time (see Common Errors and Warnings). If success is false, you will need to adjust the appointment according to all the warnings before calling Appointment Update. If success is true, the warnings will still be returned, but it will not prevent you from updating the appointment.

Common Errors and Warnings

See Appointment Update: Common Errors and Warnings.

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.
ignore_processing_duration boolean If false, the update will fail if the appointment does not have enough time for its processing_duration (when processing_duration_blocked=false). If omitted, defaults to true.
ignore_processing_duration_at_close boolean If false, the update will fail if the appointment does not have enough time for its processing_duration at the end of the day (when processing_duration_blocked=false). This allows you to ignore processing time if it clashes with other appointments, but enforce it at the end of the day (or vice versa). If omitted, defaults to ignore_processing_duration.
ignore_processing_duration_blocked boolean If false, the update will fail if the appointment does not have enough time for its processing_duration (when processing_duration_blocked=true). Only a user with a Manager level Role or higher can set this to true. If omitted, defaults to true for Manager level Roles or higher.
ignore_processing_duration_blocked_at_close boolean If false, the update will fail if the appointment does not have enough time for its processing_duration at the end of the day (when processing_duration_blocked=true). This allows you to ignore blocked processing time if it clashes with other appointments, but enforce it at the end of the day (or vice versa). Only a user with a Manager level Role or higher can set this to true. If omitted, defaults to ignore_processing_duration_blocked.
ignore_other_processing_duration_blocked boolean If false, the update will fail if the appointment is placed into another appointment's processing_duration_blocked time. Only a user with a Manager level Role or higher can set this to true. If omitted, defaults to false.
appointments 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).
show_on_appt_page This field cannot be updated - except in the special case where the appointment has the No Show appointment flag set, in which case the appointment can be updated to show_on_appt_page=false.
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.
warnings Message[] There may be warnings relating to updating this appointment - for example, a message that the appointment could be moved to this timeslot if you ignore the appointment's processing time (see Common Errors and Warnings). If success is false, you will need to adjust the appointment according to all the warnings before calling Appointment Update. If success is true, the warnings will still be returned, but the appointment will have been updated.

Common Errors and Warnings

Type Code Description
Warning APPTIGNORESPROCESSING This appointment could be placed in this timeslot, if processing time is ignored (set ignore_processing_duration=true)
Warning APPTIGNORESBLOCKEDPROCESSING This appointment could be placed in this timeslot, if blocked processing time is ignored (set ignore_processing_duration_blocked=true)
Warning APPTIGNORESOTHERBLOCKEDPROCESSING This appointment could be placed in this timeslot, if an earlier appointment's blocked processing time is ignored (set ignore_other_processing_duration_blocked=true).
Warning APPTRESIZED This appointment could be placed in this timeslot, if duration is reduced - check details field for reduced duration value.
Error APPOINTMENTSLOTUNAVAILABLE This appointment cannot be moved to this timeslot. More details may be provided in the details field.
Error FIELDUPDATENOTALLOWED This field cannot be changed. The field name will be provided in the details field.
Error FIELDUPDATENOTALLOWEDWHENPAID This field cannot be changed when the item is paid. The field name will be provided in the details field.

Update Confirm

Example Request:

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

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

Accepts or declines a requested appointment that is awaiting confirmation from the company.

HTTP Request

POST /v1/appointment/update/confirm

Request Data

Parameter Type Description
appointment_id integer required The ID of the appointment to accept or decline.
confirm boolean required true to accept the appointment, false to decline it.

Response Data

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

Update Flag

Example Request:

curl "https://apiN.simplesalon.com/v1/appointment/update/flag"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
        "appointment_id": 56789,
        "flag_id": -2
        "value": true
  }'

Example Response:

{
    "success": true,
    "appointment": 
    {
        "appointment_id": 56789,
        "client_id": 1111,
        "company_id": 12345,
        "duration": 15,
        "flag_ids": [ -2 ],
        "flags": [
            {
                "flag_id": -2,
                "name": "Arrived"
            }
        ],
        "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 the specified flag on the appointment.

HTTP Request

POST /v1/appointment/update/flag

Request Data

Parameter Type Description
appointment_id integer required The ID of the appointment to update the flag for.
flag_id integer required The ID of the flag to update. See Appointment Flags.
value boolean required Set to true if the appointment should have this flag, false if it should not.

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. Must specify appointment_id or appointment_ids.
appointment_ids integer[] required* The IDs of the appointments to delete. Must specify appointment_id or appointment_ids. Note that if there are multiple IDs specified, errors will be returned with success=true and warnings. A single appointment ID with an error will be returned with success=false and an error.

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.
appointment_ids integer[] The IDs of the appointments to retrieve.
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.
client_package_expired boolean true for appointments purchased as part of a package that have expired, false for all other appointments. If omitted, returns both.
client_package_id integer The client package ID to retrieve appointments for, or 0 for none. (Special Note: Unlinked Client Package Items)
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.
date_created_min string The creation date to retrieve appointments from (inclusive).
date_created_max string The creation date to retrieve appointments to (exclusive).
double_booked boolean true for appointments that are double booked, false for appointments that are not. If omitted, returns both.
online_booking_client_id integer The online booking client ID to filter by. client_id must be omitted, and company_id must be specified. Must include the X-Online-Booking-Client-Token HTTP header of the logged in Online Booking Client.
operator_id integer The operator ID to retrieve appointments for.
operators_only boolean If true, excludes appointments made with a resource only (with the System Operator). If omitted, defaults to false, which will include appointments booked with just a resource too.
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.
resources_only boolean If true, excludes appointments made with an operator only (no resource_id set). If omitted, defaults to false, which will include appointments booked with just an operator too.
service_id integer The service ID to filter by.
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.
sold_in_client_package boolean true for appointments purchased as part of a package, false for all other appointments. If omitted, returns both.
transaction_id integer The transaction ID to retrieve appointments for, or 0 for none. If omitted, returns both.
unconfirmed boolean true for appointments that have been requested by a third party but have not yet been accepted by the company. Eg. a booking request from a client through the online bookings website. false for all other appointments. If omitted, returns both.

Appointment

Parameter Type Description
appointment_id integer The ID of the appointment.
unpaid_expiry_time string The time that the appointment expires if unpaid. The appointment will be deleted if this expiry time is reached and the appointment has not yet had a deposit taken or a payment made.
can_redeem_via_loyalty_points boolean If true, this individual 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). See Redemption Notes.
can_redeem_via_loyalty_points_combined boolean If true, this appointment could be redeemed by spending the client's loyalty points (in conjunction with any other items checked in the same call). This field is only included when relevant (ie. with a POS-related API call). See Redemption Notes.
can_redeem_via_membership boolean If true, this individual appointment could be redeemed by claiming one of the client's membership inclusion items. This field is only included when relevant (ie. with a POS-related API call). See Redemption Notes.
can_redeem_via_membership_combined boolean If true, this appointment could be redeemed by claiming one of the client's membership inclusion items (in conjunction with any other items checked in the same call) . This field is only included when relevant (ie. with a POS-related API call). See Redemption Notes.
can_redeem_via_package boolean If true, this individual 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). See Redemption Notes.
can_redeem_via_package_combined boolean If true, this appointment could be redeemed by claiming one of the client's previously purchased (and as yet unclaimed) package items (in conjunction with any other items checked in the same call). This field is only included when relevant (ie. with a POS-related API call). See Redemption Notes.
child_appointments_price decimal The combined price of all the child services. This may or may not include tax, depending on the company's prices_inc_tax setting. Only included when parent=true. Cannot be set directly - it is calculated from the combined price fields of the child appointments.
child_appointments_price_with_tax decimal The combined price of all the child services including any tax. Only included when parent=true. Cannot be set directly - it is calculated from the combined price_with_tax fields of the child appointments.
child_appointments_price_without_tax decimal The combined price of all the child services excluding any tax. Only included when parent=true. Cannot be set directly - it is calculated from the combined price_without_tax fields of the child appointments.
child_appointments_tax_amount decimal The combined amount of tax of all the child services. Only included when parent=true. Cannot be set directly - it is calculated from the combined tax_amount fields of the child appointments.
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.
client_package_id integer If this appointment was sold as part of a package, the ID of the client package. (Special Note: Unlinked Client Package Items)
client_package ClientPackage A minimal Client Package object, to provide the package id and expiry if this appointment was sold as part of a package.
comments string The comments of the appointment.
comments_locked boolean Whether the comments for this appointment have been locked, and can no longer be changed.
company_id integer The company ID of the appointment.
confirmation_charge_calculation string Only present if unconfirmed is true, and confirming the appointment requires a fee. How the fee for confirmation is calculated, eg. 10%.
confirmation_charge_minimum_applied boolean Only present if unconfirmed is true, and confirming the appointment requires a fee. true if a minimum charge has been applied instead of the default confirmation_charge_calculation.
confirmation_charge_total string Only present if unconfirmed is true, and confirming the appointment requires a fee. The fee for confirmation, eg. $10.
confirmation_reference string Only present if unconfirmed is true. The third party's booking reference number, eg. the booking reference number from the online booking website.
date_created string The date this appointment was created.
deposit_transaction_id integer The ID of the transaction where a deposit was taken for this appointment.
discount_type_id integer The discount type ID of the appointment, or 0 for none. Obsolete - use discounts instead.
discounts Discount The list of discounts applied to the appointment.
duration integer The duration of the appointment, in minutes.
flag_ids integer[] The list of flag IDs on this appointment. See Appointment Flags.
flags AppointmentFlag[] Expanded field of flag_ids. The list of flags on this appointment. See Appointment Flags.
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. This may or may not include tax, depending on the company's prices_inc_tax setting.
price_with_tax decimal The price of the appointment including any tax. Cannot be set directly - it is calculated from the price field.
price_without_tax decimal The price of the appointment excluding any tax. Cannot be set directly - it is calculated from the price field.
redeem_via_membership boolean If true, this appointment will be redeemed by claiming one of the client's membership inclusion items. If the client does not have any of this service to redeem, the call will fail. This field should only be included with an Appointment Add call.
redeem_via_package boolean If true, this appointment will be redeemed by claiming one of the client's previously purchased (and as yet unclaimed) package items. If the client does not have any of this service to redeem, the call will fail. This field should only be included with an Appointment Add call.
resource_id integer The resource ID of the appointment, or 0 for none.
service_id integer The service ID of the appointment.
service Service The service for this appointment. For POS calls, a minimal Service object is automatically included to provide the service name and category name. For other API calls, must be specifically requested using expanded_fields.
show_on_appt_page boolean true for appointments visible on the appointment page, false for appointments not shown on the appointments page. Defaults to true for appointments added via Add Appointments, always false for appointments added via Add Transaction.
sold_in_client_package boolean true for client products purchased as part of a package, false for all other client products. If omitted, returns both.
task boolean If true, this appointment is a task for the operator, and is not a service for a client.
tax_amount decimal The amount of tax. Cannot be set directly - it is calculated from the price field.
time string The time block this appointment starts from. Valid values are: morning (starts before 12pm), lunchtime (starts between 11am and 2pm), afternoon (starts between 12pm and 5pm) and evening (starts after 5pm).
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.
unconfirmed boolean If true this appointment was requested by a third party but has not yet been accepted by the company. Eg. a booking request from a client through the online bookings website. (Note that this is different to the Confirmed flag, which relates to the client confirming the appointment.)

AppointmentOption

Parameter Type Description
appointments Appointment[] The appointment/s for this timeslot option. Only company_id, operator_id, service_id, time_start, time_end and duration fields will be set.
more_available boolean Whether more timeslots are available beyond this one. If true, more timeslot options can be retrieved by requesting a new search with the time_start set to this option's time_start plus the company's appointment interval (ie. the next potential timeslot after this one).
more_available_same_operator boolean Whether more timeslots are available beyond this one for the same combination of operators and services. If true, more timeslot options can be retrieved by requesting a new search with the same operators and services as this option, and time_start set to this option's time_start plus the company's appointment interval (ie. the next potential timeslot after this one).

AppointmentDate

Parameter Type Description
date string The date this result applies to.
times string[] The time blocks available on the day (from the list of time blocks you requested to search).

Appointment Flag

Parameter Type Description
flag_id integer The ID of the appointment flag.
name string The name of the flag.

Appointment Flags

Value Name Description
-1 Paid This appointment is paid. This flag is read-only, and cannot be changed via API.
-2 Arrived The client has arrived for this appointment.
-3 First Visit This is the client's first appointment.
-4 Requested The appointment was specifically requested (eg. can be used to indicate the client has requested this particular operator, and should not be moved to another).
-5 No Show The client did not turn up for this appointment.
-6 Confirmed This appointment has been confirmed by the client. Eg. they have replied Yes to the confirmation SMS sent out before the appointment. (Note that this is different to the unconfirmed field, which relates to the company confirming a requested appointment.)
-7 VIP This appointment is a VIP 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
fields string[] Which fields to include. Omit to return all.

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 '
  {
    "client": {
      "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.
client_ids integer[] A list of client IDs to filter clients by. Invalid IDs will be ignored (no error will be raised).
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 string Multi-field search - searches for any matches across firstname, lastname, mobile, telephone and barcode.
search_all_dome boolean 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.
deposit_balance decimal The client's deposit balance. This field is read-only. Only included when specifically requested.
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.
membership_gateway string The third party client membership gateway this client is registered with. Valid values are Third Party Link Types marked as Used For: Client Memberships.
membership_gateway_id string The ID of the client in the third party client membership gateway.
membership_gateway_status ClientMembershipGatewayStatus The status of the client in the third party client membership gateway (with gateway_refresh set to false for the request).
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.

Internal Use Client

A client_id value of -2 indicates the Internal Use client. When an item is used within the company, it can be marked as sold to the Internal 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 Internal 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 Internal 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.

System Client

A client_id value of -3 indicates the System client. This is normally used by task appointments.

The System client cannot be used to book appointments or used in a sale.

Client Images

Get

Example Request:

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

Example Response:

{
    "success": true,
    "image": "",
    "image_media_type": "image/jpeg"
}

Gets a client's image, and optionally resizes it. When resizing, the image will keep its original aspect ratio - if specifying both width and height, the image will be resized to be less than or equal to both specified sizes.

HTTP Request

POST /v1/client/image/get

Request Data

Parameter Type Description
client_id integer required The ID of the client to retrieve the image for
height integer The height to resize the image to.
width integer The width to resize the image to.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
image string The Base64 representation of the image.
image_media_type string The media type (or MIME type) of the image.

Update

Example Request:

curl "https://apiN.simplesalon.com/v1/client/image/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_id": 56789,
    "image": "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAIBAQIBAQICAgICAgICAwUDAwMDAwYEBAMFBwYHBwcGBwcICQsJCAgKCAcHCg0KCgsMDAwMBwkODw0MDgsMDAz/2wBDAQICAgMDAwYDAwYMCAcIDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAz/wAARCAABAAEDASIAAhEBAxEB/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/8QAHwEAAwEBAQEBAQEBAQAAAAAAAAECAwQFBgcICQoL/8QAtREAAgECBAQDBAcFBAQAAQJ3AAECAxEEBSExBhJBUQdhcRMiMoEIFEKRobHBCSMzUvAVYnLRChYkNOEl8RcYGRomJygpKjU2Nzg5OkNERUZHSElKU1RVVldYWVpjZGVmZ2hpanN0dXZ3eHl6goOEhYaHiImKkpOUlZaXmJmaoqOkpaanqKmqsrO0tba3uLm6wsPExcbHyMnK0tPU1dbX2Nna4uPk5ebn6Onq8vP09fb3+Pn6/9oADAMBAAIRAxEAPwD9/KKKKAP/2Q==",
    "image_media_type": "image/jpeg"
  }'

Example Response:

{
    "success": true
}

Adds or updates the image for a client.

HTTP Request

POST /v1/client/image/update

Request Data

Parameter Type Description
client_id integer required The ID of the client to update image for.
image string required The Base64 representation of the image. Total size of request must be less than 4MB.
image_media_type string required The media type (or MIME type) of the image.

Response Data

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

Delete

Example Request:

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

Example Response:

{
    "success": true
}

Deletes the image of the client.

HTTP Request

POST /v1/client/image/delete

Request Data

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

Response Data

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

Client Files

List

Example Request:

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

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "client_files": [
        {
            "client_file_id": 2736,
            "client_id": 1111,
            "company_id": 12345,
            "content_type": "image/jpeg",
            "created_operator":
            {
                "company_id": 12345,
                "display_name": "Ash",
                "firstname": "Ashley",
                "lastname": "Smith",
                "operator_id": 2222
            },
            "created_operator_id": 2222,
            "date_created": "2020-01-01T12:00:00+11:00",
            "display_filename": "before.jpg",
            "storage_filename": "https://storage.googleapis.com/simplesalon-files/12345/1111/abcdef.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=viewfiles%40simple-world-production.iam.gserviceaccount.com%2F20200101%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20200101T000000Z&X-Goog-Expires=3599&X-Goog-SignedHeaders=host&X-Goog-Signature=1234567890abcdef",
            "storage_thumbnailfilename": "https://storage.googleapis.com/simplesalon-files/12345/1111/abcdef_thumb.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=viewfiles%40simple-world-production.iam.gserviceaccount.com%2F20200101%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20200101T000000Z&X-Goog-Expires=3599&X-Goog-SignedHeaders=host&X-Goog-Signature=1234567890abcdef"
        }
    ]
}

Get a list of files associated with a client.

HTTP Request

POST /v1/client_file/list

Request Data

Parameter Type Description
filters ClientFileFilter required The filters to apply to the client file 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.
client_files ClientFile[] The list of client files matching the filters and page options.

Get

Example Request:

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

Example Response:

{
    "success": true,
    "client_file": 
    {
        "client_file_id": 2736,
        "client_id": 1111,
        "company_id": 12345,
        "content_type": "image/jpeg",
        "created_operator":
        {
            "company_id": 12345,
            "display_name": "Ash",
            "firstname": "Ashley",
            "lastname": "Smith",
            "operator_id": 2222
        },
        "created_operator_id": 2222,
        "date_created": "2020-01-01T12:00:00+11:00",
        "display_filename": "before.jpg",
        "storage_filename": "https://storage.googleapis.com/simplesalon-files/12345/1111/abcdef.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=viewfiles%40simple-world-production.iam.gserviceaccount.com%2F20200101%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20200101T000000Z&X-Goog-Expires=3599&X-Goog-SignedHeaders=host&X-Goog-Signature=1234567890abcdef",
        "storage_thumbnailfilename": "https://storage.googleapis.com/simplesalon-files/12345/1111/abcdef_thumb.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=viewfiles%40simple-world-production.iam.gserviceaccount.com%2F20200101%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20200101T000000Z&X-Goog-Expires=3599&X-Goog-SignedHeaders=host&X-Goog-Signature=1234567890abcdef"
    }
}

Gets a single client file.

HTTP Request

POST /v1/client_file/get

Request Data

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

Response Data

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

Add

Example Request:

curl "https://apiN.simplesalon.com/v1/client_file/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_file": {
      "client_id": 1111,
      "display_filename": "after.jpg"
    }
  }'

Example Response:

{
    "success": true,
    "client_file": 
    {
        "client_file_id": 2737,
        "client_id": 1111,
        "company_id": 12345,
        "content_type": "image/jpeg",
        "created_operator":
        {
            "company_id": 12345,
            "display_name": "Ash",
            "firstname": "Ashley",
            "lastname": "Smith",
            "operator_id": 2222
        },
        "created_operator_id": 2222,
        "date_created": "2020-01-01T12:00:00+11:00",
        "display_filename": "after.jpg",
        "storage_filename": "12345-2737-abcdefabcdef.jpg",
        "upload_url": "https://storage.googleapis.com/simplesalon-uploadfiles/01234?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=uploadfiles%40simple-world-production.iam.gserviceaccount.com%2F20200101%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20200101T000000Z&X-Goog-Expires=3599&X-Goog-SignedHeaders=host&X-Goog-Signature=1234567890abcdef"
    }
}

Adds a new client file. This will create an upload request with an upload_url for you to Complete the Upload.

HTTP Request

POST /v1/client_file/add

Request Data

Parameter Type Description
client_file ClientFile required The client file to add. Omitted or null fields are left as default values.
Field Notes for Add
client_file_id This field cannot be set.
client_id This field is required.
display_filename This field is required.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
client_file ClientFile The added client file awaiting upload.

Complete the Upload

Create a binary PUT request to the provided upload_url (from the Add Client File call), and include your file, as well as the content type of the file in the header (Eg. Content-Type: image/jpeg).
After the upload is complete, it may take a few moments to appear in the client's list of files.

Update

Example Request:

curl "https://apiN.simplesalon.com/v1/client_file/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_file_id": 2736,
    "display_filename": "before2.jpg"
  }'

Example Response:

{
    "success": true,
    "client_file": 
    {
        "client_file_id": 2736,
        "client_id": 1111,
        "company_id": 12345,
        "content_type": "image/jpeg",
        "created_operator":
        {
            "company_id": 12345,
            "display_name": "Ash",
            "firstname": "Ashley",
            "lastname": "Smith",
            "operator_id": 2222
        },
        "created_operator_id": 2222,
        "date_created": "2020-01-01T12:00:00+11:00",
        "display_filename": "before2.jpg",
        "storage_filename": "https://storage.googleapis.com/simplesalon-files/12345/1111/abcdef.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=viewfiles%40simple-world-production.iam.gserviceaccount.com%2F20200101%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20200101T000000Z&X-Goog-Expires=3599&X-Goog-SignedHeaders=host&X-Goog-Signature=1234567890abcdef",
        "storage_thumbnailfilename": "https://storage.googleapis.com/simplesalon-files/12345/1111/abcdef_thumb.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=viewfiles%40simple-world-production.iam.gserviceaccount.com%2F20200101%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20200101T000000Z&X-Goog-Expires=3599&X-Goog-SignedHeaders=host&X-Goog-Signature=1234567890abcdef"
    }
}

Updates an existing client file.

HTTP Request

POST /v1/client_file/update

Request Data

Parameter Type Description
client_file ClientFile required The client file to update. Must specify client_file_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.
appointment_id This field cannot be changed.

Response Data

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

Delete

Example Request:

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

Example Response:

{
    "success": true
}

Deletes a client file.

HTTP Request

POST /v1/client_file/delete

Request Data

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

Response Data

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

Models

ClientFileFilter

Parameter Type Description
client_id integer The ID of the client to retrieve files for.

ClientFile

Parameter Type Description
client_file_id integer The ID of the client file.
appointment_id integer The ID of the appointment this file relates to. This field is not required.
client_id integer The ID of the client.
company_id integer The company ID of the client. This field is read-only.
content_type string The content type of the client file.
created_operator_id integer The operator ID of the operator who uploaded the file.
created_operator Operator Expanded field of created_operator_id. The operator who uploaded the file.
date_created string The date this client file was created.
display_filename string The filename to use when displaying this file. It must end in the file's extension eg. .jpg. Only files with an image extension (.jpg/.gif/.png) will have thumbnails created.
minimum_role_id integer The minimum Role ID required to view this file. If adding a new file, omit this field to use the default setting.
storage_filename string The path to display the file. Note that the link will expire after a short amount of time. When the file is still awaiting upload, this field has the name of the file to upload.
storage_thumbnailfilename string The path to display the file's thumbnail. Note that the link will expire after a short amount of time.
upload_url string This field is only visible for a client file Add, while the file is awaiting upload. The path to upload your file to - the file must be named exactly as shown in the storage_filename field.

Client Membership Gateway

This retrieves data from the third party client membership gateway(s) linked to the Simple Salon account.

Client Status

Example Request:

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

Example Response:

{
    "success": true
}

Retrieves the status of the client. Uses the gateway already saved onto the client.

HTTP Request

POST /v1/third_party/client_membership/client/status

Request Data

Parameter Type Description
client_id integer required The ID of the client to retrieve the status for
gateway_refresh boolean If true, the status will be retrieved directly from the third party gateway (and the client will be updated if anything has changed). This request may take longer to process as it needs to wait for the third party gateway to respond. If omitted, defaults to false.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
error Message The error message details.
description string The message sent back from the third party gateway to describe the status (if status is pending or error).
fields_required string[] If status=not_linked, this field will contain any Client fields that are required before the client can be added to the default client membership gateway. If this field is an empty list, then all required fields are already filled. Omitted when status is anything other than not_linked, or there is no default client membership gateway set up.
gateway string The Client Membership Gateway that this client is linked to. Valid values are Third Party Link Types marked as Used For: Client Memberships. Omitted if no gateway is selected for the client.
status string The status of the client in the third party gateway. Valid values are: not_linked, active, pending (new, awaiting activation), error.
view_url string The link to view the client on the third party gateway's website, if any.

Client Membership Status

Example Request:

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

Example Response:

{
    "success": true
}

Gets the status of the client membership. Uses the gateway already saved onto the client membership's client.

HTTP Request

POST /v1/third_party/client_membership/client_membership/status

Request Data

Parameter Type Description
client_membership_id integer required The ID of the client membership to retrieve the status for
gateway_refresh boolean If true, the status will be retrieved directly from the third party gateway (and the client membership will be updated if anything has changed). This request may take longer to process as it needs to wait for the third party gateway to respond. If omitted, defaults to false.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
error Message The error message details.
description string The message sent back from the third party gateway to describe the status (if status is pending or error).
gateway string The Client Membership Gateway that this client (and the client membership) is linked to. Valid values are Third Party Link Types marked as Used For: Client Memberships. Omitted if no gateway is selected for the client.
status string The status of the client membership in the third party gateway. Valid values are: none (gateway link not required for this type of membership), not_linked (no gateway link), active, pending (new, awaiting activation), suspended (previously active membership was paused), cancelled, error.
view_url string The link to view the client membership on the third party gateway's website, if any.

Client Memberships

List

Example Request:

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

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "total_rows": 1,
    "client_memberships": [
        {
            "client_membership_id": 2469,
            "client_id": 1111,
            "company_id": 12345,
            "membership_id": 4646,
            "start_date": "2019-01-01T10:45:00+11:00",
            "transaction_id": 85735
        }
    ]
}

Get a list of client memberships.

HTTP Request

POST /v1/client_membership/list

Request Data

Parameter Type Description
filters ClientMembershipFilter required The filters to apply to the client memberships list
options ListOptions The options for list results.
options.expanded_fields_grouped ExpandedField[] Available fields for expanding are: clients, memberships, operators, packages.

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.
client_memberships ClientMembership[] The list of client memberships matching the filters and page options.
clients Client[] The list of clients matching the returned client memberships. Must specifically request this field via options.expanded_fields_grouped.
operators Operator[] The list of operators matching the returned client memberships. Must specifically request this field via options.expanded_fields_grouped.
memberships Membership[] The list of memberships matching the returned client memberships. Must specifically request this field via options.expanded_fields_grouped.

Get

Example Request:

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

Example Response:

{
    "success": true,
    "client_membership": 
    {
        "client_membership_id": 2469,
        "client_id": 1111,
        "company_id": 12345,
        "membership_id": 4646,
        "start_date": "2019-01-01T10:45:00+11:00",
        "transaction_id": 85735
    }
}

Gets a single client membership.

HTTP Request

POST /v1/client_membership/get

Request Data

Parameter Type Description
client_membership_id integer required The ID of the client membership to retrieve
expanded_fields ExpandedField[] Available fields for expanding are: discounts.

Response Data

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

Update

Example Request:

curl "https://apiN.simplesalon.com/v1/client_membership/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_membership": 
    {
        "client_membership_id": 2469,
        "start_date": "2019-01-02T10:45:00+11:00",
    }
  }'

Example Response:

{
    "success": true,
    "client_membership": 
    {
        "client_membership_id": 2469,
        "client_id": 1111,
        "company_id": 12345,
        "membership":
        {
            "company_id": 12345,
            "membership_id": 4646,
            "name": "1 Year Upfront",
        },
        "membership_id": 4646,
        "start_date": "2019-01-02T10:45:00+11:00",
        "transaction_id": 85735
    }
}

Updates an existing client membership.

HTTP Request

POST /v1/client_membership/update

Request Data

Parameter Type Description
client_membership ClientMembership required The client membership to update. Must specify client_membership_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.

Response Data

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

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

Client Membership Item List

Example Request:

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

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "client_membership_items": [
        {
            "client_membership_item_id": 6541,
            "quantity": 1,
            "quantity_used": 0,
            "service_id": 3333,
            "type": "service"
        },
        ...
    ],
    "period_start": "2019-01-01T00:00:00+00:00",
    "period_end": "2019-01-08T00:00:00+00:00"
}

Get the list of items that are included in a client membership (when includes_items=true on the client membership's membership).

HTTP Request

POST /v1/client_membership/item/list

Request Data

Parameter Type Description
filters ClientMembershipItemFilter required The filters to apply to the client membership item list
options ListOptions The options for list results.
options.expanded_fields ExpandedField[] Available fields for expanding are: product, service, client_membership.
options.expanded_fields_grouped ExpandedField[] Available fields for expanding are: companies.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
client_membership_items ClientMembershipItem[] The list of client membership items included in the client membership.
companies Company The list of companies matching the returned client memberships. Must specifically request this field via options.expanded_fields_grouped. Only available when using online_booking_client_id filter.

Models

Client Membership

Parameter Type Description
client_membership_id integer The ID of the client membership.
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. Obsolete - use discounts instead.
discounts Discount The list of discounts applied to the client membership.
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_id integer The ID of the membership sold to the client.
membership Membership The membership sold to the client. Must specifically request this field via expanded_fields.
membership_gateway_id string The ID of the client membership in the third party client membership gateway.
membership_gateway_status ClientMembershipGatewayStatus The status of the client membership in the third party client membership gateway (with gateway_refresh set to false for the request).
start_date string The start date of the client membership.
tax_amount decimal The amount of tax. Cannot be set directly - it is calculated from the price field.
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.

ClientMembershipFilter

Parameter Type Description
client_id integer The client ID to retrieve client memberships for.
company_id integer The company ID to retrieve client memberships for. If omitted, and client_id is also omitted, defaults to the logged in user's company ID.
date_created_min string The creation date to retrieve client memberships from (inclusive).
date_created_max string The creation date to retrieve client memberships to (exclusive).
online_booking_client_id integer The online booking client ID to filter by. client_id must be omitted, and company_id must be specified. Must include the X-Online-Booking-Client-Token HTTP header of the logged in Online Booking Client.
operator_id integer The operator ID to retrieve client memberships for.
transaction_id integer The transaction ID to retrieve client memberships for, or 0 for none. If omitted, returns both.

ClientMembershipItem

Parameter Type Description
client_membership_item_id integer The ID of the client membership item.
client_membership_id integer The ID of the client membership.
client_membership ClientMembership The client membership. Must specifically request this field via expanded_fields.
company_id integer The company ID of the client membership item.
period_end string The date the membership claim period referred to by quantity_used ends. Omitted if the membership has payment_type=upfront.
period_start string The date the membership claim period referred to by quantity_used begins (or the start date of the client membership if the membership has payment_type=upfront).
product_id integer The ID of the product (if the type is a product).
product Product The product (if the type is a product). Must specifically request this field via expanded_fields.
quantity integer The number of this item included in the client membership.
quantity_used integer The number of this item that have been claimed. For client memberships with a membership payment_type=recurring, this field only includes items used within the requested period (see period_start and period_end).
service_id integer The ID of the service (if the type is a service).
service Service The service (if the type is a service). Must specifically request this field via expanded_fields.
type string The type of this item. Valid values are product or service.

ClientMembershipItemFilter

Parameter Type Description
client_membership_id integer required* The client membership ID to retrieve client membership items for. Must specify either client_membership_id, client_id or online_booking_client_id.
client_id integer required* The client ID to retrieve client membership items for. Must specify either client_membership_id, client_id or online_booking_client_id.
online_booking_client_id integer required* The online booking client ID to filter by. client_id must be omitted, and company_id must be specified. Must include the X-Online-Booking-Client-Token HTTP header of the logged in Online Booking Client. Must specify either client_membership_id, client_id or online_booking_client_id.
all_quantity_used boolean If true, returns only client membership inclusion items where all the quantity has been used (within the requested period for client memberships with a membership with payment_type=recurring). If false, returns only client membership inclusion items where there is still some quantity remaining. If omitted, returns both.
client_membership_active boolean If true, returns only client membership inclusion items where the client membership status is active. If false, returns only client membership inclusion items where the client membership status is not active. If omitted, returns both.
company_id integer The company ID to retrieve client membership items for.
period_date string The date to check for quantity_used and all_quantity_used. If omitted, defaults to the current date.
type string The type of client membership inclusion items to return. Valid values are product or service. If omitted, returns both.

Client Packages

List

Example Request:

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

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "total_rows": 1,
    "client_packages": [
        {
            "client_package_id": 2669,
            "client_id": 1111,
            "company_id": 12345,
            "package_id": 9999,
            "price": 80
        }
    ]
}

Get a list of client packages.

HTTP Request

POST /v1/client_package/list

Request Data

Parameter Type Description
filters ClientPackageFilter required The filters to apply to the client packages list
options ListOptions The options for list results.
options.expanded_fields_grouped ExpandedField[] Available fields for expanding are: clients, operators, packages.

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.
client_packages ClientPackage[] The list of client packages matching the filters and page options.
clients Client[] The list of clients matching the returned client packages. Must specifically request this field via options.expanded_fields_grouped.
operators Operator[] The list of operators matching the returned client packages. Must specifically request this field via options.expanded_fields_grouped.
packages Package[] The list of packages matching the returned client packages. Must specifically request this field via options.expanded_fields_grouped.

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/client_package/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_package_id": 2669,
    "expanded_fields": [
        {"expanded_field": "package", "fields": ["package_id", "company_id", "name" ]}
    ]
  }'

Example Response:

{
    "success": true,
    "client_package": 
    {
        "client_package_id": 2669,
        "client_id": 1111,
        "company_id": 12345,
        "package":
        {
            "company_id": 12345,
            "package_id": 9999,
            "name": "10 x Haircut",
        },
        "package_id": 9999,
        "price": 80
    }
}

Gets a single client package.

HTTP Request

POST /v1/client_package/get

Request Data

Parameter Type Description
client_package_id integer required The ID of the client package to retrieve
expanded_fields ExpandedField[] Available fields for expanding are: discounts, package.

Response Data

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

Update

Example Request:

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

Example Response:

{
    "success": true,
    "client_package": 
    {
        "client_package_id": 2669,
        "client_id": 1111,
        "company_id": 12345,
        "package":
        {
            "company_id": 12345,
            "package_id": 9999,
            "name": "10 x Haircut",
        },
        "package_id": 9999,
        "price": 86
    }
}

Updates an existing client package.

HTTP Request

POST /v1/client_package/update

Request Data

Parameter Type Description
client_package ClientPackage required The client package to update. Must specify client_package_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.
expiry_date Set to the new date, or an empty string for no expiry.

Response Data

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

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.
date_created string The date this client package was created.
discount_type_id integer The discount type ID of the client package, or 0 for none. Obsolete - use discounts instead.
discounts Discount The list of discounts applied to the client package.
expiry_date string The expiry date of the client package. Omitted if the package never expires.
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_amount decimal The amount of tax. Cannot be set directly - it is calculated from the price field.
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.

ClientPackageFilter

Parameter Type Description
client_id integer The client ID to retrieve client packages for.
expired boolean true for client packages that have expired, false for all other client packages. If omitted, returns both.
company_id integer The company ID to retrieve client packages for. If omitted, and client_id is also omitted, defaults to the logged in user's company ID.
date_created_min string The creation date to retrieve client packages from (inclusive).
date_created_max string The creation date to retrieve client packages to (exclusive).
online_booking_client_id integer The online booking client ID to filter by. client_id must be omitted, and company_id must be specified. Must include the X-Online-Booking-Client-Token HTTP header of the logged in Online Booking Client.
operator_id integer The operator ID to retrieve client packages for.
package_id integer The package ID to retrieve client packages for.
transaction_id integer The transaction ID to retrieve client packages for, or 0 for none. If omitted, returns both.

Client Products

List

Example Request:

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

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "total_rows": 1,
    "client_products": [
        {
            "client_product_id": 3737,
            "client_id": 1111,
            "company_id": 12345,
            "product_id": 5556,
            "price": 10.00
        }
    ]
}

Get a list of client products.

HTTP Request

POST /v1/client_product/list

Request Data

Parameter Type Description
filters ClientProductFilter required The filters to apply to the client product list
options ListOptions The options for list results.
options.expanded_fields_grouped ExpandedField[] Available fields for expanding are: clients, operators, products, packages.

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.
client_products ClientProduct[] The list of client products matching the filters and page options.
clients Client[] The list of clients matching the returned client products. Must specifically request this field via options.expanded_fields_grouped.
operators Operator[] The list of operators matching the returned client products. Must specifically request this field via options.expanded_fields_grouped.
packages Package[] The list of packages matching the returned client products which were bought as part of a package (ie. client_package_id is set). Must specifically request this field via options.expanded_fields_grouped.
products Product[] The list of products matching the returned client products. Must specifically request this field via options.expanded_fields_grouped.

Get

Example Request:

curl "https://apiN.simplesalon.com/v1/client_product/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_product_id": 3737,
    "expanded_fields": [
        {"expanded_field": "product", "fields": ["product_id", "company_id", "name" ]}
    ]
  }'

Example Response:

{
    "success": true,
    "client_product": 
    {
        "client_product_id": 3737,
        "client_id": 1111,
        "company_id": 12345,
        "product":
        {
            "company_id": 12345,
            "product_id": 5556,
            "name": "Conditioner",
        },
        "product_id": 5556,
        "price": 10.00
    }
}

Gets a single client product.

HTTP Request

POST /v1/client_product/get

Request Data

Parameter Type Description
client_product_id integer required The ID of the client product to retrieve
expanded_fields ExpandedField[] Available fields for expanding are: client_package, discounts, product.

Response Data

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

Update

Example Request:

curl "https://apiN.simplesalon.com/v1/client_product/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_product": 
    {
        "client_product_id": 3737,
        "price": 13.50
    }
  }'

Example Response:

{
    "success": true,
    "client_product": 
    {
        "client_product_id": 3737,
        "client_id": 1111,
        "company_id": 12345,
        "product_id": 5556,
        "price": 13.50
    }
}

Updates an existing client product.

HTTP Request

POST /v1/client_product/update

Request Data

Parameter Type Description
client_product ClientProduct required The client product to update. Must specify client_product_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.

Response Data

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

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": 3737
  }'

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.
can_redeem_via_membership boolean If true, this client product could be redeemed by claiming one of the client's membership inclusion items. Note that if the quantity was more than 1, this field will be true if any can be claimed - check can_redeem_via_membership_quantity to see how many can be claimed. This field is only included when relevant (ie. with a POS-related API call). See Redemption Notes.
can_redeem_via_membership_combined boolean If true, this client product could be redeemed by claiming one of the client's membership inclusion items (in conjunction with any other items checked in the same call). Note that if the quantity was more than 1, this field will be true if any can be claimed - check can_redeem_via_membership_quantity_combined to see how many can be claimed. This field is only included when relevant (ie. with a POS-related API call). See Redemption Notes.
can_redeem_via_membership_quantity integer The quantity of this product the client can redeem via membership. Omitted if can_redeem_via_membership is false or omitted. This field is only included when relevant (ie. with a POS-related API call). See Redemption Notes.
can_redeem_via_membership_quantity_combined integer The quantity of this product the client can redeem via membership (in conjunction with any other items checked in the same call). Omitted if can_redeem_via_membership_combined is false or omitted. This field is only included when relevant (ie. with a POS-related API call). See Redemption Notes.
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. Note that if the quantity was more than 1, this field will be true if any can be claimed - check can_redeem_via_package_quantity to see how many can be claimed. This field is only included when relevant (ie. with a POS-related API call). See Redemption Notes.
can_redeem_via_package_combined boolean If true, this client product could be redeemed by claiming one of the client's previously purchased (and as yet unclaimed) package items (in conjunction with any other items checked in the same call). Note that if the quantity was more than 1, this field will be true if any can be claimed - check can_redeem_via_package_quantity_combined to see how many can be claimed. This field is only included when relevant (ie. with a POS-related API call). See Redemption Notes.
can_redeem_via_package_quantity integer The quantity of this product the client can redeem via package. Omitted if can_redeem_via_package is false or omitted. This field is only included when relevant (ie. with a POS-related API call). See Redemption Notes.
can_redeem_via_package_quantity_combined integer The quantity of this product the client can redeem via package (in conjunction with any other items checked in the same call). Omitted if can_redeem_via_package_combined is false or omitted. This field is only included when relevant (ie. with a POS-related API call). See Redemption Notes.
claimed boolean false for client products purchased as part of a package, that have not yet been collected, true for all other client products.
client_id integer The ID of the client the product was sold to.
client_package_id integer If this client product was sold as part of a package, the ID of the client package. (Special Note: Unlinked Client Package Items)
client_package ClientPackage A minimal Client Package object, to provide the package id and expiry if this client product was sold as part of a package.
company_id integer The company ID of the client product.
date_created string The date this client product was created.
discount_type_id integer The discount type ID of the client product, or 0 for none. Obsolete - use discounts instead.
discounts Discount The list of discounts applied to the client product.
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_id integer The ID of the product sold to the client.
product Product A minimal Product object, to provide the product name and brand name (at POS).
quantity integer The quantity of product sold to the client.
sold_in_client_package boolean true for client products purchased as part of a package, false for all other client products. If omitted, returns both.
tax_amount decimal The amount of tax. Cannot be set directly - it is calculated from the price field.
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.

ClientProductFilter

Parameter Type Description
claimed boolean false for client products purchased as part of a package, that have not yet been collected, true for all other client products. If omitted, returns both.
client_id integer The client ID to retrieve client products for.
client_package_expired boolean true for client products purchased as part of a package that have expired, false for all other client products. If omitted, returns both.
client_package_id integer The client package ID to retrieve client products for, or 0 for none. (Special Note: Unlinked Client Package Items)
company_id integer The company ID to retrieve client products for. If omitted, and client_id is also omitted, defaults to the logged in user's company ID.
date_created_min string The creation date to retrieve client products from (inclusive).
date_created_max string The creation date to retrieve client products to (exclusive).
online_booking_client_id integer The online booking client ID to filter by. client_id must be omitted, and company_id must be specified. Must include the X-Online-Booking-Client-Token HTTP header of the logged in Online Booking Client.
operator_id integer The operator ID to retrieve client products for.
sold_in_client_package boolean true for client products purchased as part of a package, false for all other client products. If omitted, returns both.
product_id integer The product ID to retrieve client products for.
transaction_id integer The transaction ID to retrieve client products for, or 0 for none. If omitted, returns both.

Client Vouchers

List

Example Request:

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

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "total_rows": 1,
    "client_vouchers": [
        {
            "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
        },
        ...
    ]
}

Get a list of client vouchers.

HTTP Request

POST /v1/client_voucher/list

Request Data

Parameter Type Description
filters ClientVoucherFilter required The filters to apply to the client voucher list
options ListOptions The options for list results.
options.expanded_fields_grouped ExpandedField[] Available fields for expanding are: clients, operators, vouchers.

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.
client_vouchers ClientVoucher[] The list of client vouchers matching the filters and page options.
clients Client[] The list of clients matching the returned client vouchers. Must specifically request this field via options.expanded_fields_grouped.
operators Operator[] The list of operators matching the returned client vouchers. Must specifically request this field via options.expanded_fields_grouped.
vouchers Voucher[] The list of vouchers matching the returned client vouchers. Must specifically request this field via options.expanded_fields_grouped.

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
expanded_fields ExpandedField[] Available fields for expanding are: discounts.

Response Data

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

Update

Example Request:

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

Example Response:

{
    "success": true,
    "client_voucher": 
    {
        "client_voucher_id": 2769,
        "client_id": 1111,
        "company_id": 12345,
        "voucher":
        {
            "company_id": 12345,
            "voucher_id": 7777,
            "name": "$100 Gift Voucher",
        },
        "voucher_id": 7777,
        "price": 101
    }
}

Updates an existing client voucher.

HTTP Request

POST /v1/client_voucher/update

Request Data

Parameter Type Description
client_voucher ClientVoucher required The client voucher to update. Must specify client_voucher_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.

Response Data

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

Delete

Example Request:

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

Example Response:

{
    "success": true
}

Deletes a client voucher.

HTTP Request

POST /v1/client_voucher/delete

Request Data

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

Response Data

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

Send

Example Request:

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

Example Response:

{
    "success": true
}

Sends a client voucher to the client.

HTTP Request

POST /v1/client_voucher/send

Request Data

Parameter Type Description
client_voucher_id integer required The ID of the client voucher to send
email string The email address to send to. If omitted, it will default to the email address of the client. If set to an empty string, no email will be sent.
mobile string The mobile/cell number to send to. If omitted, it will default to the mobile/cell number of the client. If set to an empty string, no SMS will be sent.

Response Data

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

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. Obsolete - use discounts instead.
discounts Discount The list of discounts applied to the client voucher.
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.
online_booking_last_sent_date string The date the client voucher was last sent via Online Bookings.
online_booking_last_sent_email string The email the client voucher was last sent to via Online Bookings.
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.

ClientVoucherFilter

Parameter Type Description
barcode string The barcode to retrieve client vouchers for.
client_id integer The client ID to retrieve client vouchers for.
company_id integer The company ID to retrieve client vouchers for. If omitted, and client_id is also omitted, defaults to the logged in user's company ID.
date_created_min string The creation date to retrieve client vouchers from (inclusive).
date_created_max string The creation date to retrieve client vouchers to (exclusive).
expired boolean true for client vouchers that have expired, false for all other client vouchers. If omitted, returns both.
online_booking_client_id integer The online booking client ID to filter by. client_id must be omitted, and company_id must be specified. Must include the X-Online-Booking-Client-Token HTTP header of the logged in Online Booking Client.
operator_id integer The operator ID to retrieve client vouchers for.
search_all_dome boolean If you are in a dome, setting this to true will search for client vouchers across all companies. If omitted, defaults to false to search only the user's company.
type string The voucher type to filter by. Valid values are cash or item. If omitted, returns both.
transaction_id integer The transaction ID to retrieve client vouchers for, or 0 for none. If omitted, returns both.
voucher_id integer The voucher ID to retrieve client vouchers for.

Client Payment Types

List

Example Request:

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

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "client_payment_types": [
        {
            "online_booking_client_id": 2828,
            "gateway": "slick",
            "extra_fields": [
                {
                    "extra_field": "external_id",
                    "value": "3490"
                },
                {
                    "extra_field": "card_number",
                    "value": "#### #### #### 4242"
                }
            ]
        },
        ...
    ]
}

Get a list of client payment types.

HTTP Request

POST /v1/client_payment_type/list

Request Data

Parameter Type Description
filters ClientPaymentTypeFilter required The filters to apply to the client payment type 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).
client_payment_types ClientPaymentType[] The list of client payment types matching the filters.

Add

Example Request:

curl "https://apiN.simplesalon.com/v1/client_payment_type/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_payment_type": 
    {
        "online_booking_client_id": 2828,
        "gateway": "slick",
        "extra_fields": [
            {
                "extra_field": "token",
                "value": "tok_1JUkoX2eZvKYlo2CF0CEp82y"
            }
        ]
    }
  }'

Example Response:

{
    "success": true,
    "client_payment_type": 
    {
        "online_booking_client_id": 2828,
        "gateway": "slick",
        "extra_fields": [
            {
                "extra_field": "external_id",
                "value": "3490"
            },
            {
                "extra_field": "card_number",
                "value": "#### #### #### 4242"
            }
        ]
    }
}

Adds a new client payment type.

HTTP Request

POST /v1/client_payment_type/add

Request Data

Parameter Type Description
client_payment_type ClientPaymentType required The client payment type to add.
client_payment_type.extra_fields string[] The extra field keys required by this client payment type for an add. See Client Payment Type Extra Fields for that gateway.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
client_payment_type ClientPaymentType The new client payment type.

Delete

Example Request:

curl "https://apiN.simplesalon.com/v1/client_payment_type/delete"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
        "online_booking_client_id": 2828,
        "gateway": "slick",
        "extra_fields": [
            {
                "extra_field": "external_id",
                "value": "3490"
            }
        ]
  }'

Example Response:

{
    "success": true
}

Deletes a client payment type.

HTTP Request

POST /v1/client_payment_type/delete

Request Data

Parameter Type Description
online_booking_client_id integer The ID of the online booking client that the client payment type is linked to.
gateway string The gateway for this client payment type.
extra_fields string[] The extra field keys required by this client payment type for deletion. See Client Payment Type Extra Fields for that gateway.

Response Data

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

Extra Fields

These are the Extra Fields used for client payment types.

Slick

The calls to Client Payment Method functions for the slick gateway require the extra HTTP Header of the logged in Online Booking Client (matching the online_booking_client_id) also passed in.

HTTP Headers

Header Value
Content-Type Always application/json
Authorization Your Login Token for your Partner (in format: Bearer abcdef).
X-Online-Booking-Client-Token The Online Booking Client Token returned for the online booking client who has logged in (either via Online Booking Client Login or Online Booking Client Add).

Add

Extra Field Description
token The Stripe token for the card to add to this Online Booking Client. To generate the token, use Stripe, with API key pk_test_i1rfWDOMQeHmEZiqk1ju2zoI for the Sandbox Test Environment, and pk_live_AVl0xnOWARieiUhBmF6FBiem for the live environment.

Get

Extra Field Description
external_id The ID of the card that can be charged.
card_number The (obscured) credit card number.
card_type The brand of credit card (eg. Visa or MasterCard).

Delete

Extra Field Description
external_id The ID of the card to delete.

Models

Client Payment Type

Parameter Type Description
online_booking_client_id integer The ID of the online booking client that the client payment type is linked to.
gateway string The gateway for this client payment type. Valid values are slick.
extra_fields string[] The extra field keys required by this client payment type. See Client Payment Type Extra Fields for that gateway.

ClientPaymentTypeFilter

Parameter Type Description
gateway string The gateway that the client payment type can be used for. Valid values are slick.
online_booking_client_id integer The online booking client ID to filter by. Must specify gateway=slick and include the X-Online-Booking-Client-Token HTTP header of the logged in Online Booking Client.

Communications

Campaign Get

Example Request:

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

Example Response:

{
    "success": true,
    "campaign": 
    {
        "automatic": false,
        "campaign_id": 674644,
        "company_id": 12345,
        "date_created": "2019-01-01T11:00:00+11:00",
        "media": "email",
        "name": "Confirmation Email",
        "status": "sent",
        "type": "confirmation"
    }
}

Gets a single campaign.

HTTP Request

POST /v1/campaign/get

Request Data

Parameter Type Description
campaign_id integer required The ID of the campaign to retrieve

Response Data

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

Recipient List

Example Request:

curl "https://apiN.simplesalon.com/v1/campaign/recipient/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        "client_id": 1111,
        "date_created_min":"2019-01-01T00:00:00+00:00",
        "date_created_max":"2019-01-02T00:00:00+00:00",
        ...
    },
    "options":
    {
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "recipients": [
        {
            "appointment_id": 56789,
            "campaign_id": 674644,
            "client_id": 1111,
            "company_id": 12345,
            "date_created": "2019-01-01T11:00:00+11:00",
            "recipient_id": 346919852,
            "type": "client"
        }
    ]
}

Get a list of recipients.

HTTP Request

POST /v1/campaign/recipient/list

Request Data

Parameter Type Description
filters RecipientFilter required The filters to apply to the recipient list
options ListOptions The options for list results.
options.expanded_fields ExpandedField Available fields for expanding are: campaign.

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.
recipients Recipient[] The list of campaign recipients matching the filters and page options.

Recipient Get

Example Request:

curl "https://apiN.simplesalon.com/v1/campaign/recipient/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "recipient_id": 346919852
  }'

Example Response:

{
    "success": true,
    "recipient": 
    {
        "appointment_id": 56789,
        "campaign_id": 674644,
        "client_id": 1111,
        "company_id": 12345,
        "date_created": "2019-01-01T11:00:00+11:00",
        "recipient_id": 346919852,
        "type": "client"
    }
}

Gets a single recipient.

HTTP Request

POST /v1/campaign/recipient/get

Request Data

Parameter Type Description
recipient_id integer required The ID of the recipient to retrieve
expanded_fields ExpandedField Available fields for expanding are: campaign.

Response Data

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

Message List

Example Request:

curl "https://apiN.simplesalon.com/v1/campaign/recipient/message/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        "recipient_id": 346919852,
        "date_created_min":"2019-01-01T00:00:00+00:00",
        "date_created_max":"2019-01-02T00:00:00+00:00",
        ...
    },
    "options":
    {
        ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "messages": [
        {
            "recipient_id": 346919852,
            "company_id": 12345,
            "date_created": "2019-01-01T11:00:00+11:00",
            "external_id": "msg_anjfdhrfrd",
            "message_id": 95463464466,
            "message": "Happy Birthday! Enjoy 10% off for the whole month of your birthday.",
            "status": "queued",
            "type": "message_sent"
        }
    ]
}

Get a list of message replies.

HTTP Request

POST /v1/campaign/recipient/message/list

Request Data

Parameter Type Description
filters MessageFilter required The filters to apply to the message list
options ListOptions The options for list results.
options.sort_expression string Available fields for sorting are: date_sent (default)

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.
messages Message[] The list of messages matching the filters and page options.

Message Get

Example Request:

curl "https://apiN.simplesalon.com/v1/campaign/recipient/message/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "message_id": 95463464466
  }'

Example Response:

{
    "success": true,
    "message": 
    {
        "recipient_id": 346919852,
        "company_id": 12345,
        "date_created": "2019-01-01T11:00:00+11:00",
        "external_id": "msg_anjfdhrfrd",
        "message_id": 95463464466,
        "message": "Happy Birthday! Enjoy 10% off for the whole month of your birthday.",
        "status": "queued",
        "type": "message_sent"
    }
}

Gets a single message.

HTTP Request

POST /v1/campaign/recipient/message/get

Request Data

Parameter Type Description
message_id integer required The ID of the message to retrieve

Response Data

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

Send Push

Example Request:

curl "https://apiN.simplesalon.com/v1/send/push"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "operator_id": 2222,
    "title": "Client Arrived",
    "message":"Client Joe has arrived for their 10:45am appointment.",
    "category":"client_arrived",
    "expiry_date":"2019-01-01T11:15:00+11:00"
  }'

Example Response:

{
    "success": true
}

Sends a push notification message to the relevant push devices.

HTTP Request

POST /v1/send/push

Request Data

Parameter Type Description
operator_id integer required* The ID of the operator to send the push notification to. Must specify either operator_id or role_id.
role_id integer required* The ID of the role to send the push notification to (a message will be sent to all operators of that role). Must specify either operator_id or role_id.
category string required The category for the notification. Valid values are client_arrived or appointment_pending.
message string required The content of the notification.
title string required The title of the notification.
expiry_date string The date when the message should be discarded, if not yet delivered. See Dates.

Response Data

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

Send SMS

Example Request:

curl "https://apiN.simplesalon.com/v1/send/sms"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_id": 2222,
    "message":"Client Joe has arrived for their 10:45am appointment."
  }'

Example Response:

{
    "success": true
}

Sends an SMS message to the client's mobile number.

HTTP Request

POST /v1/send/sms

Request Data

Parameter Type Description
client_id integer required The ID of the client to send the message to.
message string required The content of the message.

Response Data

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

Send Template

Example Request:

curl "https://apiN.simplesalon.com/v1/send/template"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "template_type": "booking_confirmation",
    "appointment_id": 56789
  }'

Example Response:

{
    "success": true
}

Sends a template message to the relevant operators/clients/users.
If a template_id is specified, the media for that template (email or sms) will determine how the message is sent to the recipients. If a template_type is specified, the message will be sent via the default methods for that template type, eg. a booking_confirmation message would be sent via SMS and Email, if both are enabled on the client (and SMS is enabled and set up for the company).

HTTP Request

POST /v1/send/template

Request Data

Parameter Type Description
template_id integer required* The ID of the template to send - the media for this template (email or sms) will determine how it is sent to the recipients. Must specify either template_id or template_type.
template_type string required* The inbuilt template type to send. Must specify either template_id or template_type. Valid values are booking_confirmation (requires appointment_id).
appointment_id integer The ID of the appointment this message relates to (any appointment fields within the template will be filled with the details of this appointment).
client_id integer The ID of the client to send this message to (any client fields within the template will be filled with the details of this client).
operator_id string The ID of the operator to send this message to (any operator fields within the template will be filled with the details of this operator).

Response Data

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

Send SMS Price Check

Example Request:

curl "https://apiN.simplesalon.com/v1/send/sms/check"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "message": "Hi #ClientFirstName#, this is your reminder for your 10:45am appointment at #CompanyName#. Please make sure to fill out the new patient form. Reply Y to confirm 😄"
  }'

Example Response:

{
    "success": true,
    "credits": 3,
    "character_count_used": 158,
    "character_count_sms_gsm": 157,
    "character_count_sms_remaining": 42,
    "character_count_sms_used": 159,
    "character_count_sms_unicode": 2,
    "message": "Hi #ClientFirstName#, this is your reminder for your 10:45am appointment at Company A. Please make sure to fill out the new patient form. Reply Y to confirm 😄",
    "message_single": "Hi #ClientFirstName#, this is your reminder for your 10:45am"
}

Estimates the cost of an SMS message.

A single SMS message can be 160 characters for a basic alphanumeric message, or 70 characters for a single message containing UTF8 characters (emojis, or international characters).
For a longer SMS message, the SMS can be sent as a combined SMS if enabled (see the company's allow_multiple_sms setting). A combined SMS can be 612 characters for a basic alphanumeric message, or 268 characters for a message containing UTF8 characters.

Template tags relating to the company will have the correct value inserted before the estimate is made.
Other template tags may incur additional cost when sent. For example, when the length of an inserted tag value (eg. John B. Citizen, 15 characters) is longer than the length of the tag used in the estimate (eg. #ClientName#, 12 characters), and that length difference exceeds the character_count_sms_remaining.

HTTP Request

POST /v1/send/sms/check

Request Data

Parameter Type Description
template_id integer required* The ID of the template to estimate price for. Must specify either template_id or message.
message string required* The content of the message to estimate price for. Must specify either template_id or message.
recipient_count integer The number of recipients the message will be sent to - to calculate the estimated total prices. If omitted, defaults to 1.
quote boolean If true, the response will include the current SMS balance data, and the estimated amount of that balance that will be used. This takes longer to return, and records the quote in the log, so it should only be true once the user indicates that they are ready to send the campaign. Basic character count checks should leave this as false. If omitted, defaults to false.
expanded_fields ExpandedField[] Available fields for expanding are: balance.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
balance SMS Balance The current SMS balance data. Must be specifically requested using expanded fields or by setting quote=true.
character_count_sms_remaining integer The number of characters remaining in this SMS message before another credit is required (special characters and/or emojis may require more than one character).
character_count_sms_gsm integer The number of characters in this message that can be sent via GSM7 encoding (special characters may have required more than one GSM7 character).
character_count_sms_unicode integer The number of characters in this message that require UTF8 encoding (special characters and/or emojis may have required more than one UTF8 character).
character_count_sms_used integer The number of characters in this message when sent via SMS (special characters and/or emojis may have required more than one character). This will equal character_count_sms_gsm + character_count_sms_unicode.
credits integer The estimated number of credits required to send this message to one recipient. If the company has disabled their allow_multiple_sms setting, any value greater than 1 means the message will not be sent at all.
message string The final message used to estimate price. Company template tags will be replaced, and any characters exceeding the maximum for a combined SMS will be truncated.
message_single string The message to send if you want to restrict the message to a single SMS (ie. if the company has disabled their allow_multiple_sms setting). Company template tags will be replaced, and any characters exceeding the maximum for a single SMS will be truncated.
recipient_count integer The number of recipients the total_amount, free_credits_used, funds_used, and any upgrade recommendations, are based on.
total_credits decimal The total estimated amount of credits for sending this message to this client_count. Does not take into account any free credits. This will equal credits x clent_count.
free_credits_used integer The amount of free_credits estimated to be used by sending this message. This will be the lesser of balance.free_credits and total_credits. Must be specifically requested by setting quote=true.
funds_used decimal The amount of funds estimated to be used by sending this message. This will equal (total_credits - free_credits_used) x credit_price. Must be specifically requested by setting quote=true.
funds_required decimal If funds_used is greater than balance.funds, this will be the difference. Otherwise, it will be 0. Must be specifically requested by setting quote=true.
topup_quote SMSQuote If funds_required is greater than 0, this will be the detailed quote for purchasing the required topup amount. Note that topups are at set intervals, so the amount to purchase for topup (topup_quote.amount) will usually be greater than the amount in funds_required. Must be specifically requested by setting quote=true.

Models

Campaign

Parameter Type Description
campaign_id integer The ID of the campaign.
automatic boolean true if this is an automatic/scheduled campaign, false if this campaign was manually queued.
company_id integer The company ID of the message.
date_created string The date this message was created.
media string The media type of campaign. Valid values are email and sms.
name string The name of the campaign.
template_id integer The ID of the template for this campaign.
type string The type of campaign. Valid values are adhoc, reminder, reminder_second, birthday, first_visit, online_booking, online_booking_alert, confirmation, confirmation_with_invoice, invoice, order, no_recent_visit, voucher, admin, one_touch_marketing.
status string The status of this campaign. Valid values are building, pending, sending and sent.

RecipientFilter

Parameter Type Description
date_created_min string required* The creation date to retrieve recipients from (inclusive). Required if campaign_id is omitted.
date_created_max string required* The creation date to retrieve recipients to (exclusive). Required if campaign_id is omitted.
campaign_id integer The campaign ID to retrieve recipients for.
client_id integer The client ID to retrieve recipients for.
company_id integer The company ID to retrieve recipients for.
status string The recipient status to filter by.

MessageFilter

Parameter Type Description
date_created_min string required* The creation date to retrieve message replies from (inclusive). Required if message_id is omitted.
date_created_max string required* The creation date to retrieve message replies to (exclusive). Required if message_id is omitted.
company_id integer The company ID to retrieve message replies for.
recipient_id integer The recipient ID to retrieve message replies for.
client_id integer The client ID to retrieve message replies for (when campaign.type=client).
status string The message reply status to filter by.
type string The message reply type to filter by.

Recipient

Parameter Type Description
recipient_id integer The ID of the campaign recipient.
appointment_id integer The ID of the appointment this recipient relates to.
campaign_id integer The ID of the campaign.
campaign Campaign The campaign for this recipient. Must be specifically requested using expanded_fields.
client_id integer The client ID of the recipient (when type=client).
company_id integer The company ID of the recipient.
date_created string The date this recipient was created.
type string The type of recipient this message relates to. Valid values are adhoc, client, company, operator and supplier.

Message

Parameter Type Description
message_id integer The ID of the message.
company_id integer The company ID of the message.
date_created string The date this message was created.
date_sent string The date this message was sent/received.
external_id string The ID returned from the provider for this message.
recipient_id integer The ID of the campaign recipient this message relates to.
recipient Recipient The campaign recipient for this message. Must be specifically requested using expanded_fields.
message_text string The text of the message.
receiver string The receiver address.
sender string The sender address.
status string The status of this message. Valid values are none, queued (queued at the messaging provider), delivered and failed. Note that the status will be updated on the type=sent reply, but not on any other messages with the same recipient_id - they will retain the status they had at creation.
type string The type of message. Valid values are message_sent, message_received, dlr (delivery reports generated after the message is queued) and send_error (errors generated before the message is queued).

Companies

List

Example Request:

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

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "companies": [
        {
            "company_id": 12345,
            "name": "Company A"
        },
        ...
    ]
}

Get a list of companies. Only relevant for Dome companies.

HTTP Request

POST /v1/company/list

Request Data

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

Response Data

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

Get

Example Request:

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

Example Response:

{
    "success": true,
    "company": 
    {
        "company_id": 12345,
        "name": "Company A"
    }
}

Gets a single company.

HTTP Request

POST /v1/company/get

Request Data

Parameter Type Description
company_id integer required* The ID of the company to retrieve. Must specify either company_id, online_booking_company_id or online_booking_url_id.
online_booking_company_id integer required* The online booking ID of the company to retrieve. Must specify either company_id, online_booking_company_id or online_booking_url_id.
online_booking_url_id integer required* The online booking URL ID of the company to retrieve. Must specify either company_id, online_booking_company_id or online_booking_url_id.

Response Data

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

Models

Company

Parameter Type Description
company_id integer The ID of the company.
dome boolean true if the company is a Dome parent company.
dome_company_id integer The ID of the company's dome parent, if any.
dome_online_booking_company_id integer The ID of the company's dome parent online booking store, if any.
address_line1 string The street address of the company's postal address.
address_suburb string The suburb of the company's postal address.
address_postcode string The postcode/zipcode of the company's postal address.
address_state_id integer The geographical state ID of the company's postal address.
address_state State Expanded field of address_state_id. The geographical state of the company's postal address.
country_code string The 2-letter ISO 3166-1 code of the company's country.
country Country Expanded field of country_code. The company's country.
currency_code string The 3-letter ISO 4217 code of the company's currency.
currency_symbol string The company's currency symbol.
name string The name of the company.
online_booking_company_id integer The company's online booking store ID.
phone string The telephone number of the company.
website string The website address of the company.

CompanyFilter

Parameter Type Description
dome_company_id integer The company ID of the Dome to retrieve child companies for. If omitted, defaults to the logged in user's company ID.
online_booking_show boolean The online booking visibility to filter by. If omitted, returns all.

Countries

List

Example Request:

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

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "countries": [
        {
            "country_code": "AU",
            "name": "Australia",
            "currency_symbol": "$",
            "currency_code": "AUD"
        },
        ...
    ]
}

Get a list of countries.

HTTP Request

POST /v1/country/list

Request Data

Parameter Type Description
options ListOptions The options for list results.
options.rows_per_page integer Can be set to -1 to retrieve all matching countries.

Response Data

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

Models

Country

Parameter Type Description
country_code string The 2-letter ISO 3166-1 code of the country.
name string The country's name.
currency_symbol string The default currency symbol to use when displaying prices.
currency_code string The default 3-letter ISO 4217 code of the country's currency.

Discounts

Models

Discount

Parameter Type Description
discount_id integer The ID of the discount.
amount decimal The amount of the discount.
appointment_id integer The ID of the appointment (if the type is a appointment).
client_package_id integer The ID of the client package (if the type is a client_package).
client_product_id integer The ID of the client product (if the type is a client_product).
client_membership_id integer The ID of the client membership (if the type is a client_membership).
client_voucher_id integer The ID of the client voucher (if the type is a client_voucher).
company_id integer The company ID of the discount type.
date_created string The date the discount was created.
discount_type_id integer The ID of the Discount Type.
discount_type Discount Type[] The discount type.
item_type string The type of item this discount is applied to. Valid values are appointment, client_package, client_product, client_membership, client_voucher.
operator_id integer The ID of the [Operator](#operators-models-operator] who applied the discount.
order integer The order this discount should be applied to the item, for multiple discounts. Note that discounts with transaction_discount=true must be after all the discounts with transaction_discount=false.
original_price decimal The price before the discount was applied ie. the price that the discount was calculated on for a percentage item discount.
pos_id string Your unique identifier for an unsaved discount. Only used in the POS Transaction Price Check and Add Transaction API calls. Required for Transaction Discount.
tax_amount decimal The amount of tax adjusted by the discount.
transaction_discount boolean If true, this discount is a Transaction Discount. If false, this discount is applied to the individual item.
transaction_id integer The ID of the Transaction this discount is applied to.

Special Values

Transaction Discount

If transaction_discount is true, this discount has been applied to the whole transaction, not just this particular item. The entry on this particular item shows only the proportion of discount applied to this one item.
For example, a transaction with a price=10.00 appointment and a price=30.00 client product, with a $10.00 transaction discount applied, will have a discounts entry for the appointment (amount=2.50) and a discounts entry for the client product (amount=7.50).

Transaction Discounts must have pos_id set when sent, to enable them to be distinguished if multiple transaction discounts are applied.

Transaction Discounts do not apply to Tips or Account Values - percentage Transaction Discount types are calculated on the transaction amount minus these item amounts, and there will not be a discounts entry created on these items.

Discount Types

List

Example Request:

curl "https://apiN.simplesalon.com/v1/discount_type/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
        ...
    },
    "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
filters DiscountTypeFilter required The filters to apply to the discount type list
company_id integer The ID of the company requesting the list. If omitted, defaults to the logged in user's company ID. Dome users must specify a child location.
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.
apply_automatically boolean true if this discount is set to apply to eligible items automatically, false if it's not.
client_category_ids integer[] The list of client category IDs this discount is permitted to be applied to. If omitted, all clients regardless of their categories are permitted.
company_id integer The company ID of the discount type.
discount_type string The type of discount. Valid values are $ and %.
discount_type_items DiscountTypeItem[] The list of items this discount is permitted to be applied to. If omitted, this discount type can be applied to any item.
name string The name of the discount type.
role_ids integer[] The IDs of the operator Roles who are permitted to apply this discount. If omitted, all roles are permitted.
available_days string[] The list of days this discount is eligible to be applied on. If omitted, no days are permitted (this discount cannot be applied at all).
time_start string If this discount is limited to a specific date range, the date from which this discount is permitted to be applied. If omitted, this discount type is not limited to specific dates. See Dates.
time_end string If this discount is limited to a specific date range, the date to which this discount is permitted to be applied. If omitted, this discount type is not limited to specific dates. See Dates.

Discount Type Item

Parameter Type Description
discount_type_item_id integer The ID of the discount type item.
brand_id integer The ID of the brand (if the type is a brand).
category_id integer The ID of the category (if the type is a category).
membership_id integer The ID of the membership (if the type is a membership).
package_id integer The ID of the package (if the type is a package).
product_id integer The ID of the product (if the type is a product).
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, service, package, membership, brand, category, all_products, all_services, all_packages, all_memberships or transaction.

DiscountTypeFilter

Parameter Type Description
client_ids integer[] Only return discounts that can be applied to this list of clients (based on their Client Categories and/or Client Memberships). If any client has a match for the discount, the discount will be returned. If an empty list is sent, all discounts restricted by client will be excluded.
day string The day of the week to filter discounts by. Discounts that are not restricted by day will also be returned.
item_type string The DiscountTypeItem type restriction to filter by. Valid values are all (discounts which have no item restrictions), product, service, package, membership, brand, category, all_products, all_services, all_packages, all_memberships or transaction.
role_id integer The Role ID to filter by. Discounts that are not restricted by role will also be returned.
time string Only return discounts that can be applied on this date (discounts that contain this date in their limited date range, as well as discounts that are not limited by date range). Automatically applies the day filter if it was omitted. See Dates.

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

Live Payment Types

Terminal List

Example Request:

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

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "terminals": [
        {
            "external_id": "tmr_J6U4YwUIK1TX54H94WOwDKXx",
            "company_id": 12345,
            "name": "Front Bench",
            "serial": "123-456-789",
            "type": "verifone_P400",
            "status": "online"
        },
        ...
    ]
}

Get a list of live payment type terminals (if supported).

HTTP Request

POST /v1/third_party/payment_type/terminal/list

Request Data

Parameter Type Description
gateway string The Live Payment Gateway to request terminals from. If omitted, defaults to the default POS payment gateway for the company. Valid values are Third Party Link Types marked as Used For: Payment Type.
filters TerminalFilter The filters to apply to the terminal list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all terminals (depending on third party support).

Response Data

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

Terminal Get

Example Request:

curl "https://apiN.simplesalon.com/v1/third_party/payment_type/terminal/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "gateway": "stripe",
    "external_id": "tmr_J6U4YwUIK1TX54H94WOwDKXx"
  }'

Example Response:

{
    "success": true,
    "terminal": {
        "external_id": "tmr_J6U4YwUIK1TX54H94WOwDKXx",
        "company_id": 12345,
        "name": "Front Bench",
        "serial": "123-456-789",
        "type": "verifone_P400",
        "status": "online"
    }
}

Get a live payment type terminal (if supported).

HTTP Request

POST /v1/third_party/payment_type/terminal/get

Request Data

Parameter Type Description
gateway string The Live Payment Gateway to request the terminal from. If omitted, defaults to the default POS payment gateway for the company. Valid values are Third Party Link Types marked as Used For: Payment Type.
terminal_id string required* The ID of the terminal. Must specify either terminal_id or external_id (depending on third party support).
external_id string required* The ID of the terminal in the third party. Must specify either terminal_id or external_id (depending on third party support).

Response Data

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

Terminal Add

Example Request:

curl "https://apiN.simplesalon.com/v1/third_party/payment_type/terminal/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "gateway": "stripe",
    "terminal": 
    {
        "pairing_code": "your-generated-code",
        "name": "Front Bench"
    }
  }'

Example Response:

{
    "success": true,
    "terminal": 
    {
        "external_id": "tmr_J6U4YwUIK1TX54H94WOwDKXx",
        "company_id": 12345,
        "name": "Front Bench",
        "serial": "123-456-789",
        "type": "verifone_P400",
        "status": "online"
    }
}

Links a new terminal.

HTTP Request

POST /v1/third_party/payment_type/terminal/add

Request Data

Parameter Type Description
gateway string The Live Payment Gateway to request terminals from. If omitted, defaults to the default POS payment gateway for the company. Valid values are Third Party Link Types marked as Used For: Payment Type.
terminal Terminal required The terminal to add.

Response Data

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

Terminal Delete

Example Request:

curl "https://apiN.simplesalon.com/v1/third_party/payment_type/terminal/delete"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "gateway": "stripe",
    "external_id": "tmr_J6U4YwUIK1TX54H94WOwDKXx"
  }'

Example Response:

{
    "success": true
}

Deletes a live payment type terminal (if supported).

HTTP Request

POST /v1/third_party/payment_type/terminal/delete

Request Data

Parameter Type Description
gateway string The Live Payment Gateway to delete the terminal from. If omitted, defaults to the default POS payment gateway for the company. Valid values are Third Party Link Types marked as Used For: Payment Type.
terminal_id string required* The ID of the terminal. Must specify either terminal_id or external_id (depending on third party support).
external_id string required* The ID of the terminal in the third party. Must specify either terminal_id or external_id (depending on third party support).

Response Data

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

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 for a sale transaction:

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

Request fields for Process Live Payment for a refund transaction:

Required Fields Value
gateway afterpay
original_payment_id The payment_id of the original sale payment made via Afterpay, to refund.

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

Resonance

Use with a Resonance terminal to take card payments in person.

Request fields for Process Live Payment:

These required fields apply for both a sale or refund transaction.

Required Fields Value
gateway resonance
mode eftpos or afterpay. If omitted, defaults to eftpos.

This call will trigger the Resonance terminal to begin taking payment. Once payment is confirmed, Resonance will automatically add the payment to the transaction - do not call Add Payment.

Stripe

Take payment through Stripe.
Note that not all steps need to be performed - the process depends on what type of Stripe payment you are taking.

Stripe Terminal sale transaction

Use a hardware terminal to take card payments in person:

Notes for Terminals:

Stripe Hosted Invoice sale transaction

Use with a Stripe Hosted Invoice page to take card payments by sending the client a link:

Request fields for Process Live Payment for a sale transaction:

Terminal Step 1

Request a Connection Token for using Stripe Terminal.

Request Fields Value
mode terminal
step 1
Response Extra Fields Description
connection_token The connection token returned from Stripe.

Terminal Step 2

Create a Payment Intent.

Request Fields Extra Fields Value
mode terminal
step 2
Response Extra Fields Description
payment_intent_id The ID of the payment intent created in Stripe.

Terminal Step 3

Capture a Payment Intent.

Request Fields Value
mode terminal
step 3
barcode The payment intent ID created in Step 2, that has now been linked to a payment (payment has been authorised in Stripe).

Payment is processed automatically in Step 3, do not call Add Payment.

Invoice Step 1

Create a Stripe Invoice for the transaction.

Request Fields Extra Fields Value
mode invoice
step 1
extra_fields client_id The ID of the client to create the invoice in Stripe for. If omitted, and the transaction has a single client, defaults to that client. If omitted, and there are multiple clients (or no clients) in the transaction, an error will be returned.
expiry_minutes The number of minutes the client has to pay the invoice before it is marked overdue in Stripe. Note that an overdue invoice can still be paid. If set to 0 or omitted, the invoice expires at the end of the day.
send_email Valid values are: stripe (the client will automatically be sent an email containing the invoice, from Stripe), none (no email is sent). If the client does not have an email address, an error will be returned if this field is anything but none. If omitted, defaults to none.

A pending_payment will be returned - a payment with an amount of zero - to indicate that this transaction has been invoiced via Stripe. When the Stripe invoice is paid, the pending payment will be updated with the full payment data fields and amount.

Response Extra Fields Description
invoice_url The URL of the page where the client needs to go to arrange payment.
email The email address the invoice was sent to (ie. the email address of the client).

Payment is processed automatically once the client has paid - do not call Add Payment. If there are no other pending payments remaining in the transaction, the transaction will automatically be completed.

Tyro

Use with a Tyro hardware terminal to take card payments in person.

Notes for Terminals

Models

TerminalFilter

Parameter Type Description
status string The status of the terminal. Valid values are: online, offline.

Terminal

Parameter Type Description
terminal_id integer The ID of the terminal.
company_id integer The company ID of the terminal.
external_id string The ID of the terminal in the third party.
merchant_id string The ID of the merchant in the third party.
name string The name or description of the terminal.
pairing_code string The pairing code for the terminal - only used for a Terminal Add call.
serial string The serial number of the terminal.
status string The status of the terminal.
type string The hardware type of this terminal.

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.

Sharing Update

Example Request:

curl "https://apiN.simplesalon.com/v1/membership/sharing/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "membership_id": 4646,
    "company_ids": 
    [
        12345,
        12346
    ],
    "share": true
  }'

Example Response:

{
    "success": true
}

Updates the sharing of a membership in a Dome.

HTTP Request

POST /v1/membership/sharing/update

Request Data

Parameter Type Description
voucher_id integer required The ID of the membership to update sharing on.
company_ids integer[] required The IDs of the child companies to updating sharing on.
share boolean required Set to true to share this membership with these companies. Set to false to remove sharing of this membership from these companies.
replace boolean If true, any child companies not included in the company_ids list will also have their sharing updated to the opposite value of share. If false, child companies not included in the company_ids list will keep their existing sharing value for this membership. Defaults to false if omitted.

Response Data

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

Models

Membership

Parameter Type Description
membership_id integer The ID of the membership.
checkin_allowance_number integer The amount of check in visits included in the membership, in combination with checkin_allowance_type.
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_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_service_id integer The service ID to record when the client checks in.
discount_type_id integer If this membership has a discount, the ID of the linked Discount Type.
discount_type DiscountType Expanded field of discount_type_id.
dome_membership_id integer The ID of the membership in the Dome.
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.
includes_items boolean If true, this membership includes items that can be claimed every membership period (if payment_type=recurring) or once per membership (if payment_type=upfront). If false, no items are included.
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.
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.
name string The name of the membership.
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.
setup_fee decimal The joining fee, charged at sale.
suspension_allowed boolean If true, this type of membership can be suspended.
tax Tax Rate The tax rate applied to this service. Omitted if tax_free=true.
tax_free boolean If true, this membership does not have tax applied.
tax_id_override boolean The specific Tax Rate to apply to this membership. If 0, the default tax_for_memberships rate will be applied. Omitted if tax_free=true.

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.

Online Booking

Client Login

Example Request:

curl "https://apiN.simplesalon.com/v1/online_booking/client/login"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "online_booking_company_id": 9494,
    "email": "joe@example.com",
    "login_password": "Password123",
    "login_provider": "email"
  }'

Example Response:

{
    "success": true,
    "token": "ghijkl",
    "online_booking_client": 
    {
        "country_code": "AU",
        "email": "joe@example.com",
        "email_reminders_enabled": false,
        "email_verified": true,
        "firstname": "Joe",
        "lastname": "Citizen",
        "login_provider": "email",
        "mobile": "0400000000",
        "mobile_verified": true,
        "online_booking_client_id": 2828,
        "sms_reminders_enabled": true
    }
}

Attempts to login an online booking client.
Note that these are clients from the Online Booking system, not clients for a particular company.

Social logins can use the Online Booking Client Add method when they are not sure if the login is a new or existing user (if the user exists, and the login matches, the user will be logged in instead of added).
See Online Booking Client Add for specific fields and IDs for social logins.

HTTP Request

POST /v1/online_booking/client/login

HTTP Headers

Header Value
Content-Type Always application/json
Authorization Your Login Token for your Partner (in format: Bearer abcdef).

Request Data

Parameter Type Description
email string The online booking client's email address (email or facebook login). Blank for a google or apple login.
login_password string The online booking client's password (email login), or token (access token from google or facebook login, ID token for an apple login).
login_provider string required The login provider. Valid values are email, facebook, google, apple.
login_provider_id string The online booking client's third-party login ID (Facebook ID for a facebook login, authorisation code for an apple login). Blank for an email login.
online_booking_company_id integer The ID of the location the client is viewing at the time of the login - this is to ensure the correct branding on any automated messages (such as verification emails) is displayed.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
online_booking_client Online Booking Client The online booking client.
token string The Online Booking Client Token for use with the other online booking client functions. Everytime the token is used, its expiry will be set to 1 day from the current time.

Client Get

Example Request:

curl "https://apiN.simplesalon.com/v1/online_booking/client/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -H 'X-Online-Booking-Client-Token: ghijkl' \
  -d '
  {
    "online_booking_client_id": 2828
  }'

Example Response:

{
    "success": true,
    "online_booking_client": 
    {
        "country_code": "AU",
        "email": "joe@example.com",
        "email_reminders_enabled": false,
        "email_verified": true,
        "firstname": "Joe",
        "lastname": "Citizen",
        "login_provider": "email",
        "mobile": "0400000000",
        "mobile_verified": true,
        "online_booking_client_id": 2828,
        "sms_reminders_enabled": true
    }
}

Gets the online booking client.
Note that these are clients from the Online Booking system, not clients for a particular company.

HTTP Request

POST /v1/online_booking/client/get

HTTP Headers

Header Value
Content-Type Always application/json
Authorization Your Login Token for your Partner (in format: Bearer abcdef).
X-Online-Booking-Client-Token The Online Booking Client Token returned for the online booking client who has logged in (either via Online Booking Client Login or Online Booking Client Add).

Request Data

Parameter Type Description
online_booking_client_id integer required The ID of the online booking client to retrieve. Note that it must be the same as the online booking client who logged in.

Response Data

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

Client Add

Example Request:

curl "https://apiN.simplesalon.com/v1/online_booking/client/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "online_booking_company_id": 9494,
    "online_booking_client": 
    {
        "country_code": "AU",
        "email": "joe@example.com",
        "email_reminders_enabled": false,
        "firstname": "Joe",
        "lastname": "Citizen",
        "login_password": "Password123",
        "login_provider": "email",
        "mobile": "0400000000",
        "sms_reminders_enabled": true
    }
  }'

Example Response:

{
    "success": true,
    "token": "ghijkl",
    "online_booking_client": 
    {
        "country_code": "AU",
        "email": "joe@example.com",
        "email_reminders_enabled": false,
        "email_verified": false,
        "firstname": "Joe",
        "lastname": "Citizen",
        "login_provider": "email",
        "mobile": "0400000000",
        "mobile_verified": false,
        "online_booking_client_id": 2828,
        "sms_reminders_enabled": true
    }
}

Adds a new online booking client.
Note that these are clients from the Online Booking system, not clients for a particular company.

For an email login, use the following values:

For a google login, use the following values:

For a facebook login, use the following values:

For an apple login, use the following values:

HTTP Request

POST /v1/online_booking/client/add

HTTP Headers

Header Value
Content-Type Always application/json
Authorization Your Login Token for your Partner (in format: Bearer abcdef).

Request Data

Parameter Type Description
online_booking_client Online Booking Client required The online booking client to add.
online_booking_company_id integer The ID of the location the client is viewing at the time of the add - this is to ensure the correct branding on any automated messages (such as verification emails) is displayed.
online_booking_client.login_password string The online booking client's password (email login), or token (access token from google or facebook login, ID token for an apple login).
login_provider string required The login provider. Valid values are email, facebook, google, apple.
online_booking_client.login_provider_id string The online booking client's third-party login ID (Facebook ID for a facebook login, authorisation code for an apple login). Blank for an email login.
online_booking_client.online_booking_company_id integer The ID of the location the client is viewing at the time of the login - this is to ensure the correct branding on any automated messages (such as verification emails) is displayed.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
online_booking_client Online Booking Client The new online booking client.
token string The Online Booking Client Token for performing other online booking client related functions. Everytime the token is used, its expiry will be set to 1 day from the current time.

Client Update

Example Request:

curl "https://apiN.simplesalon.com/v1/online_booking/client/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -H 'X-Online-Booking-Client-Token: ghijkl' \
  -d '
  {
    "online_booking_company_id": 9494,
    "online_booking_client": 
    {
        "online_booking_client_id": 2828,
        "firstname": "Joseph"
    }
  }'

Example Response:

{
    "success": true,
    "online_booking_client": 
    {
        "country_code": "AU",
        "email": "joe@example.com",
        "email_reminders_enabled": false,
        "email_verified": true,
        "firstname": "Joseph",
        "lastname": "Citizen",
        "login_provider": "email",
        "mobile": "0400000000",
        "mobile_verified": true,
        "online_booking_client_id": 2828,
        "sms_reminders_enabled": true
    }
}

Updates the existing online booking client.
Note that these are clients from the Online Booking system, not clients for a particular company.

HTTP Request

POST /v1/online_booking/client/update

HTTP Headers

Header Value
Content-Type Always application/json
Authorization Your Login Token for your Partner (in format: Bearer abcdef).
X-Online-Booking-Client-Token The Online Booking Client Token returned for the online booking client who has logged in (either via Online Booking Client Login or Online Booking Client Add).

Request Data

Parameter Type Description
online_booking_client Online Booking Client required The online booking client to update. Must specify online_booking_client_id. Omitted or null fields are left unchanged. Note that it must be the same as the online booking client who logged in.
online_booking_company_id integer The ID of the location the client is viewing at the time of the update - this is to ensure the correct branding on any automated messages (such as verification emails) is displayed.
Field Notes for Update
online_booking_client_id This field cannot be changed.
email_verified This field cannot be changed.
login_provider This field cannot be changed.
password This field cannot be changed if login_provider is not email.
mobile_verified This field cannot be changed.

Response Data

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

Client Reset Password

Example Request:

curl "https://apiN.simplesalon.com/v1/online_booking/client/reset_login_password"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "email": "joe@example.com",
    "online_booking_company_id": 9494
  }'

Example Response:

{
    "success": true
}

Sends the online booking client an email to reset their password.

HTTP Request

POST /v1/online_booking/client/reset_login_password

HTTP Headers

Header Value
Content-Type Always application/json
Authorization Your Login Token for your Partner (in format: Bearer abcdef).

Request Data

Parameter Type Description
email string required The email of the online booking client to reset password for.
online_booking_company_id integer The ID of the location the client is viewing at the time - this is to ensure the correct branding on any automated messages (such as verification emails) is displayed.

Response Data

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

Client Verify

Example Request:

curl "https://apiN.simplesalon.com/v1/online_booking/client/verify"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -H 'X-Online-Booking-Client-Token: ghijkl' \
  -d '
  {
    "online_booking_client_id": 2828,
    "online_booking_company_id": 9494,
    "verification_type": "mobile",
    "verification_code": 7065
  }'

Example Response:

{
    "success": true
}

Verifies the online booking client's contact information.

HTTP Request

POST /v1/online_booking/client/verify

HTTP Headers

Header Value
Content-Type Always application/json
Authorization Your Login Token for your Partner (in format: Bearer abcdef).
X-Online-Booking-Client-Token The Online Booking Client Token returned for the online booking client who has logged in (either via Online Booking Client Login or Online Booking Client Add). Not required for an email verification.

Request Data

Parameter Type Description
online_booking_client_id integer required The ID of the online booking client to verify. Note that it must be the same as the online booking client who logged in.
verification_type string required The type of verification. Valid values are email and mobile.
verification_code integer required The verification code received by the online booking client.
online_booking_company_id integer The ID of the location the client is viewing at the time - this is to ensure the correct branding on any automated messages (such as verification emails) is displayed.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors). If a verification_type=mobile request succeeded, mobile_verified will now be true for the online booking client.

Client Verify Resend

Example Request:

curl "https://apiN.simplesalon.com/v1/online_booking/client/verify/resend"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -H 'X-Online-Booking-Client-Token: ghijkl' \
  -d '
  {
    "online_booking_client_id": 2828,
    "online_booking_company_id": 9494,
    "verification_type": "mobile"
  }'

Example Response:

{
    "success": true
}

Resends the code to verify the online booking client's contact information.
Note that the verification code may take some time to come through to the user's device.

HTTP Request

POST /v1/online_booking/client/verify/resend

HTTP Headers

Header Value
Content-Type Always application/json
Authorization Your Login Token for your Partner (in format: Bearer abcdef).
X-Online-Booking-Client-Token The Online Booking Client Token returned for the online booking client who has logged in (either via Online Booking Client Login or Online Booking Client Add).

Request Data

Parameter Type Description
online_booking_client_id integer required The ID of the online booking client to resend the verification code for. Note that it must be the same as the online booking client who logged in.
verification_type string required The type of verification. Valid values are mobile or email.
online_booking_company_id integer The ID of the location the client is viewing at the time - this is to ensure the correct branding on any automated messages (such as verification emails) is displayed.

Response Data

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

Client Voucher Send

Example Request:

curl "https://apiN.simplesalon.com/v1/online_booking/client_voucher/send"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_voucher_id": 2769,
    "email": "joe@example.com",
    "online_booking_company_id": 9494,
    "name": "Joe",
    "message": "Happy Birthday!"
  }'

Example Response:

{
    "success": true
}

Sends a client voucher to the client via the Online Bookings system.

HTTP Request

POST /v1/online_booking/client_voucher/send

HTTP Headers

Header Value
Content-Type Always application/json
Authorization Your Login Token for your Partner (in format: Bearer abcdef).
X-Online-Booking-Client-Token The Online Booking Client Token returned for the online booking client who has logged in (either via Online Booking Client Login or Online Booking Client Add).

Request Data

Parameter Type Description
client_voucher_id integer required* The ID of the client voucher to send. Must specify either client_voucher_id or barcode.
barcode string required* The barcode of the client voucher to send. Must specify either client_voucher_id or barcode.
email string required The email to send the voucher to.
name string required The name of the person to send the voucher to.
message string required The message to include in the voucher notification.
online_booking_company_id integer required The ID of the location the voucher is from - this is to ensure the correct branding is displayed.

Response Data

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

Client Booking List

Example Request:

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

Example Response:

{
    "success": true,
    "more_available": true,
    "online_booking_appointments": [
        {
            "appointments": [
                "duration": 30,
                "operator_id": 2222,
                "service_id": 3333,
                "time_end": "2019-01-01T11:15:00+11:00",
                "time_start": "2019-01-01T10:45:00+11:00"
            ],
            "company": {
                "company_id": 12345,
                "name": "Company A"
            },
            "cancellable": false,
            "cancellable_reason": "not_enough_notice",
            "cancelled_by_client": false,
            "deposit_paid": false,
            "online_booking_appointment_id": 9191
            "online_booking_company_id": 9494,
            "online_booking_url_id": 55887,
            "online_booking_url_tag": "company-a"
        },
        ...
    ]
}

Lists the appointments for the client.

HTTP Request

POST /v1/online_booking/client/appointment/list

HTTP Headers

Header Value
Content-Type Always application/json
Authorization Your Login Token for your Partner (in format: Bearer abcdef).
X-Online-Booking-Client-Token The Online Booking Client Token returned for the online booking client who has logged in (either via Online Booking Client Login or Online Booking Client Add).

Request Data

Parameter Type Description
filters.online_booking_client_id integer required The ID of the client to retrieve online bookings for.
options ListOptions The options for list results. Note that return_total is always false.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
more_available boolean true if more appointments are available to request, false if you are at the end of the appointment list.
online_booking_appointments OnlineBooking[] The bookings for this client.

Client Booking Add

Example Request:

curl "https://apiN.simplesalon.com/v1/online_booking/client/appointment/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "online_booking_company_id": 9494,
    "online_booking_appointments": [
        {
            "operator_id": 2222,
            "time_start": "2019-01-01T10:45:00+11:00",
            "service_id": 3333
        },
        ...
    ],
    "online_booking_payments": [
        {
            "type": "slick",
            "online_booking_client_payment_id": 3490,
            "amount": 12.45
        },
        {
            "type": "voucher",
            "barcode": "900000000123",
            "amount": 50.00
        }
    ]
  }'

Example Response:

{
    "success": true,
    "online_booking_appointments": {
        "appointments": [
            {
                "duration": 30,
                "operator_id": 2222,
                "service_id": 3333,
                "time_end": "2019-01-01T11:15:00+11:00",
                "time_start": "2019-01-01T10:45:00+11:00"
            }
        ]
    },
    "online_booking_transaction_id": 1300,
    "payment_status": "approved",
    "status": "pending"
}

Books the client's appointment.

HTTP Request

POST /v1/online_booking/client/appointment/add

HTTP Headers

Header Value
Content-Type Always application/json
Authorization Your Login Token for your Partner (in format: Bearer abcdef).
X-Online-Booking-Client-Token The Online Booking Client Token returned for the online booking client who has logged in (either via Online Booking Client Login or Online Booking Client Add).

Request Data

Parameter Type Description
online_booking_appointments OnlineBooking[] required* The appointments to book. Must specify either online_booking_appointments or client_vouchers, but not both. Only the fields listed below are used.
online_booking_appointments. online_booking_appointment. operator_id integer required The ID of the operator of the appointment.
online_booking_appointments. online_booking_appointment. price decimal required The price of the appointment.
online_booking_appointments. online_booking_appointment. redeem_via_membership boolean If true, this appointment will be paid for by claiming one of the client's membership inclusion items. See Redemption Notes.
online_booking_appointments. online_booking_appointment. redeem_via_package boolean If true, this appointment will be paid for via a pre-purchased package service from the client's account. See Redemption Notes.
online_booking_appointments. online_booking_appointment. service_id integer required The ID of the service of the appointment.
online_booking_appointments. online_booking_appointment. time_start string required The time of the appointment.
online_booking_company_id integer required The online booking ID of the company.
client_vouchers ClientVoucher[] required* The vouchers to purchase. Must specify either online_booking_appointments or client_vouchers, but not both. Only the fields listed below are used.
client_vouchers. client_voucher. voucher_id integer required The ID of the voucher to purchase.
client_vouchers. client_voucher. price decimal required The total price of the voucher/s.
client_vouchers. client_voucher. quantity integer required The quantity of the voucher to purchase.
online_booking_payments OnlineBookingPayment[] The payment method to use for the booking/purchase. Required if this is a client_vouchers purchase. Only one payment with type=slick is allowed.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
payment_status string The status of the online booking transaction payment (if payment was taken through the slick gateway). Valid values are approved, declined, error, refunded.
status string The status of the online booking transaction. Valid values are confirmed (the company automatically accepted the booking request), rejected (the company automatically rejected the booking request), pending (the booking request is awaiting manual confirmation from the company), paymentfailed (the user's payment failed - check payment_status).
online_booking_appointments OnlineBooking[] The appointments booked.
client_vouchers ClientVoucher[] The vouchers purchased. Currently only returned if there is a single voucher purchased only (in order to facilitate sending that voucher immediately).

Client Booking Cancel

Example Request:

curl "https://apiN.simplesalon.com/v1/online_booking/client/appointment/cancel"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "online_booking_appointment_id": 9191
  }'

Example Response:

{
    "success": true,
    "deposit_refunded": false
}

Cancels the client's appointment.

HTTP Request

POST /v1/online_booking/client/appointment/cancel

HTTP Headers

Header Value
Content-Type Always application/json
Authorization Your Login Token for your Partner (in format: Bearer abcdef).
X-Online-Booking-Client-Token The Online Booking Client Token returned for the online booking client who has logged in (either via Online Booking Client Login or Online Booking Client Add).

Request Data

Parameter Type Description
online_booking_appointment_id integer required The ID of the appointment to cancel.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
deposit_refunded boolean true if this appointment had a deposit paid, which has now been refunded. false if the appointment had a deposit paid, but the deposit has since been applied to another purchase, so it cannot be refunded. false if the appointment was paid upfront or not prepaid.

Models

Online Booking Client

Parameter Type Description
online_booking_client_id integer The ID of the online booking client.
country_code string The 2-letter ISO 3166-1 code of the online booking client's country.
email string The online booking client's email address.
email_reminders_enabled boolean Whether the online booking client would like to be notified of booking changes via email.
email_verified boolean Whether the online booking client's email address has been verified.
firstname string The online booking client's first name.
image_url string The online booking client's profile image URL.
lastname string The online booking client's last name.
login_password string The password for a login_provider=email online booking client, or the login token for a third-party login (when login_provider is not email).
login_provider string The login provider. Valid values are email, facebook, google, apple.
login_provider_id string The login provider ID for a third-party login (ie. login_provider is not email).
mobile string The online booking client's mobile number.
mobile_verified boolean Whether the online booking client's mobile number has been verified.
sms_reminders_enabled boolean Whether the online booking client would like to be notified of booking changes via SMS.

Online Booking

Parameter Type Description
online_booking_appointment_id integer The ID of the online booking.
appointments Appointment[] The list of appointments part of this booking.
company Company The company the online booking was made at.
cancellable boolean true if this booking can be cancelled, false if not.
cancellable_reason string If cancellable is false, the reason why this online booking cannot be cancelled. Valid values are: cancelled (the online booking has already been cancelled - see also the cancelled_by_client field), not_booked_online (only online bookings booked through Online Bookings can be cancelled through Online Bookings), not_enough_notice (the time between now and the online booking start time is less than the company's minimum cancellation period), paid_in_full (the online booking has already been paid and processed), past (the online booking is in the past).
cancelled_by_client boolean true if this online booking was cancelled by the client, false if it was cancelled by the company.
deposit_paid boolean true if a deposit was taken for this booking, false if it was paid upfront or not prepaid.
duration integer The duration of all included appointments.
online_booking_company_id integer The online booking ID of the company.
online_booking_transaction_id integer The ID of the online booking transaction. Omitted if the online booking was not prepaid.
online_booking_url_id integer The numeric online booking URL ID of the company.
online_booking_url_tag string The human-readable online booking URL tag of the company.
status string The status of the online booking. Valid values are pending (waiting for the company to accept the booking request), confirmed (accepted bookings), rejected (for both rejected bookings, and bookings that were accepted but then cancelled later), completed (accepted bookings in the past).
time_start string The start time of the online booking.

OnlineBookingPayment

Parameter Type Description
online_booking_client_payment_id integer When type=slick, the ID of the client's online booking payment method to use (the external_id returned from Client Payment Types List with gateway=slick).
barcode string When type=voucher, the barcode of the voucher to use.
amount decimal The amount to pay using this payment type.
type string The type of payment type. Valid values are slick or voucher

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.

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

Add Push Device

Example Request:

curl "https://apiN.simplesalon.com/v1/operator/push/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "operator_id": 2222,
    "push_device": 
    {
        "name": "Lee iPhone",
        "token": "abcdef",
        "type": "apple",
        "uuid": "zyxwvu"
    }
  }'

Example Response:

{
    "success": true
}

Registers a mobile device for push notifications for the specified operator.
If the device matches an existing device, the existing device will be updated.

HTTP Request

POST /v1/operator/push/add

Request Data

Parameter Type Description
operator_id integer required The ID of the operator to register the device to.
push_device PushDevice required The device to update. Must specify all fields.

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.

Sharing Update

Example Request:

curl "https://apiN.simplesalon.com/v1/operator/sharing/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "operator_id": 2222,
    "company_ids": 
    [
        12345,
        12346
    ],
    "share": true
  }'

Example Response:

{
    "success": true
}

Updates the sharing of an operator in a Dome.

HTTP Request

POST /v1/operator/sharing/update

Request Data

Parameter Type Description
operator_id integer required The ID of the operator to update sharing on.
company_ids integer[] required The IDs of the child companies to updating sharing on.
share boolean required Set to true to share this operator with these companies. Set to false to remove sharing of this operator from these companies.
replace boolean If true, any child companies not included in the company_ids list will also have their sharing updated to the opposite value of share. If false, child companies not included in the company_ids list will keep their existing sharing value for this operator. Defaults to false if omitted.

Response Data

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

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.
online_booking_show boolean Whether the operator is visible on your online booking website.
order_num integer The display order of the operator.
phone string The telephone number of the operator.
pin integer 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.
username string The username of the operator.
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.
online_booking_show boolean The online booking visibility to filter by. If omitted, returns all.
operator_ids integer[] A list of operator IDs to filter operators by. Invalid IDs will be ignored (no error will be raised).
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.
show_on_pos_page boolean true for operators visible on the POS page, false for operators not shown directly on the POS 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.

Push Device

Parameter Type Description
name string The display name of the device.
token string The device's token.
type string The type of device. Valid values are apple and android.
uuid string The device's unique ID.

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

Wait List Operator

An operator_id value of -2 indicates the Wait List Operator - ie. the appointment is on the Wait List, and an operator (and timeslot) has not yet been assigned.

Appointments on the Wait List will have their standard duration returned.
If displayed in a list of timeslots (such as on the Appointments page), they should be displayed with only the minimum duration (the company's appointment interval), in order to fit as many in for the day as possible.

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.

Sharing Update

Example Request:

curl "https://apiN.simplesalon.com/v1/package/sharing/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "package_id": 9999,
    "company_ids": 
    [
        12345,
        12346
    ],
    "share": true
  }'

Example Response:

{
    "success": true
}

Updates the sharing of a package in a Dome.

HTTP Request

POST /v1/package/sharing/update

Request Data

Parameter Type Description
package_id integer required The ID of the package to update sharing on.
company_ids integer[] required The IDs of the child companies to updating sharing on.
share boolean required Set to true to share this package with these companies. Set to false to remove sharing of this package from these companies.
replace boolean If true, any child companies not included in the company_ids list will also have their sharing updated to the opposite value of share. If false, child companies not included in the company_ids list will keep their existing sharing value for this package. Defaults to false if omitted.

Response Data

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

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 Tax Rate The tax rate applied to this package. Omitted if tax_free=true.
tax_free boolean If true, this package does not have tax applied.
tax_id_override boolean The specific Tax Rate to apply to this package. If 0, the default tax_for_packages rate will be applied. Omitted if tax_free=true.

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.

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. See Payment Type Extra Fields and Live Payment types.
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.
gateway_modes PaymentTypeMode[] The options for the gateway mode for Live Payment types that can take payments in multiple ways.
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

Payment Type Mode

Parameter Type Description
mode string The mode identifier.
name string The name of the payment type mode.

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,
            "can_redeem_via_membership": 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,
            "can_redeem_via_membership": 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.
appointment_ids integer[] The IDs of the appointments to retrieve. If omitted, returns all unpaid appointments for today or earlier.
client_membership_ids integer[] The IDs of the client memberships to retrieve. If omitted, returns all unpaid client memberships for the client.
client_package_ids integer[] The IDs of the client packages to retrieve. If omitted, returns all unpaid client packages for the client.
client_product_ids integer[] The IDs of the client products to retrieve. If omitted, returns all unpaid client products for the client.

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.
deposit_payments DepositPayment[] The list of outstanding deposits for this client, to optionally use towards payment of the sale.
redirect_to_transaction_id integer If set, this client already has an invoice in progress - redirect to that one instead of starting a new transaction. The item lists will still contain the lists of unpaid items for this client.

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,
    "appointments": [
        {
            "client_id": 1111,
            "appointment_id": 56789,
            "operator_id": -1,
            "pos_id": "myref1",
            "price": 10.03,
            "service_id": 3333
        }
    ]
}

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

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).
appointments Appointment[] The list of appointments saved.
client_packages ClientPackage[] The list of client packages saved.
client_products ClientProduct[] The list of client products saved.
client_memberships ClientMembership[] The list of client memberships saved.

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,
        "can_redeem_via_membership": 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, loyalty_points_to_redeem (if redeemable via loyalty points), can_redeem_via_package and can_redeem_via_membership 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,
            "can_redeem_via_membership": 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,
            "can_redeem_via_membership": 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 Membership Redeem

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/service/membership_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 membership inclusion 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/membership_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.

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.

Service Package Restore

Example Request:

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

Example Response:

{
    "success": true
}

Restores the service back to the client's unclaimed package services.
The appointment will also be removed from the appointments page (if show_on_appt_page was true).

HTTP Request

POST /v1/pos/service/package_restore

Request Data

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

Response Data

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

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,
        "can_redeem_via_membership": false,
        "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), can_redeem_via_package and can_redeem_via_membership fields filled out.

Product Membership Redeem

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/product/membership_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 membership inclusion 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/membership_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).

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.

Cash Drawer Get

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/drawer/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json'

Example Response:

{
    "success": true,
    "amount": 350.50
}

Returns the amount of cash that should currently be in the cash drawer.

HTTP Request

POST /v1/pos/drawer/get

Request Data

Parameter Type Description
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).
amount decimal The amount of cash that should currently be in the drawer.

Cash Drawer Open

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/drawer/open"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json'

Example Response:

{
    "success": true
}

Logs an opening of the cash drawer (outside of normal transactions). Note that this does not actually open any cash drawers - it is simply for logging the opening of the cash drawer by the user.

HTTP Request

POST /v1/pos/drawer/open

Request Data

Parameter Type Description
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).

Transaction Price Check

Example Request:

curl "https://apiN.simplesalon.com/v1/pos/transaction/check"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "transaction": {
        "amount": 29.00,
        "appointments": [
            {
                "appointment_id": -1,
                "client_id": 1111,
                "operator_id": 2222,
                "pos_id": "myref1",
                "service_id": 3333,
                "price": 20.00
            }
        ],
        "client_products": [
            {
                "client_product_id": -1,
                "client_id": 1111,
                "company_id": 12345,
                "discounts": [
                    {
                        "amount": 1.00,
                        "discount_type_id": 7171,
                        "operator_id": 2222,
                        "order": 1,
                        "original_price": 10.00,
                        "pos_id": "myitemdiscref1",
                        "transaction_discount": false
                    }
                ],
                "product_id": 5556,
                "price": 9.00
            }
        ]
        "transaction_id": 85735
    },
    "discounts": [
        {
            "amount": 1.00,
            "discount_type_id": 7171,
            "operator_id": 2222,
            "pos_id": "mytransdiscref1",
            "transaction_discount": true
        }
    ]
  }'

Example Response:

{
    "success": true,
    "transaction": {
        "amount": 26.10,
        "appointments": [
            {
                "appointment_id": -1,
                "client_id": 1111,
                "operator_id": 2222,
                "pos_id": "myref1",
                "service_id": 3333,
                "price": 18.00,
                "discounts": [
                    {
                        "amount": 2.00,
                        "discount_type_id": 7171,
                        "operator_id": 2222,
                        "order": 1,
                        "original_price": 20.00,
                        "pos_id": "mytransdiscref1",
                        "transaction_discount": true
                    }
                ]
            }
        ],
        "client_products": [
            {
                "client_product_id": -1,
                "client_id": 1111,
                "company_id": 12345,
                "discounts": [
                    {
                        "amount": 1.00,
                        "discount_type_id": 7171,
                        "operator_id": 2222,
                        "order": 1,
                        "original_price": 10.00,
                        "pos_id": "myitemdiscref1",
                        "transaction_discount": false
                    },
                    {
                        "amount": 0.90,
                        "discount_type_id": 7171,
                        "operator_id": 2222,
                        "order": 2,
                        "original_price": 9.00,
                        "pos_id": "mytransdiscref1",
                        "transaction_discount": true
                    }
                ],
                "product_id": 5556,
                "price": 8.10
            }
        ]
    }
}

Returns the total of the transaction, any redeemable options for each item, plus applies any Transaction Discounts passed in (ie. calculates which items should be discounted, and by how much).
Existing Transaction Discounts are always recalculated (based on the original_price of the first transaction discount).

HTTP Request

POST /v1/pos/transaction/check

Request Data

Parameter Type Description
transaction Transaction required The transaction to total.
discounts Discount Any new Transaction Discount to add to these items.
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).
transaction Transaction The recalculated transaction, with amount set to the total, redeemable items identified (fields can_redeem_via_package, can_redeem_via_membership, can_redeem_via_loyalty_points, loyalty_points_to_redeem if redeemable via loyalty points, package_quantity_to_redeem if products are redeemable via package), plus any new Transaction Discount set on individual items.

Redemption Notes

Packages

When a client has previously purchased a Client Package, the items included in that Package are added to the client's account as package items (sold_in_client_package=true) and marked available for claiming (claimed=false).

Package items can be claimed via:

Membership Inclusions

When a client has an active Client Membership, the items included in that Membership become available for claiming.
For a membership with payment_type=upfront, the items can only be claimed up to the item quantity for the life of the membership.
For a membership with payment_type=recurring, the items can be claimed up to the item quantity for each period length - ie. if recurring_type=weekly, then each set of items can be claimed again each week.

Membership inclusion items can be claimed via:

Loyalty Points

When a client is part of the Loyalty Program (ie. has loyalty_member=true), they accumulate points on each purchase, based on the loyalty_points_earned value of each purchased item. Once the client has reached the minimum threshold for spending Loyalty Points, they can choose to use the points to purchase an item that they have enough points for, based on the loyalty_points_to_redeem value of that item.
When loyalty_points_to_redeem is true on an item, loyalty_points_to_redeem will be set to the amount of points required to redeem that item.

Loyalty points can be spent via:

Example of redemption fields:

A client has a single Haircut service left in their unclaimed Client Packages, and they are purchasing two Haircuts at once.
When calling Transaction Price Check:

  • Both Haircut appointments will be returned with can_redeem_via_package=true, since either service can individually be claimed via package.
  • However, can_redeem_via_package_combined will only be true for one of the Haircut appointments, because in total, the client can only claim one.

Example Response:

{
    "success": true,
    "transaction": {
        "appointments": [
            {
                "appointment_id": -1,
                "client_id": 1111,
                "service_id": 3333,
                "can_redeem_via_package": true,
                "can_redeem_via_package_combined": true,
                ...
            },
            {
                "appointment_id": -1,
                "client_id": 1111,
                "service_id": 3333,
                "can_redeem_via_package": true,
                "can_redeem_via_package_combined": false,
                ...
            }
        ],
        ...
    }
}

Individual redemption fields

Fields can_redeem_via_package, can_redeem_via_membership, can_redeem_via_loyalty_points will be marked as true if the client could redeem that particular item individually.

For a multiple quantity item, the can_redeem_via_package and can_redeem_via_membership fields will be set to true if at least one item can be claimed - check the can_redeem_via_package_quantity and can_redeem_via_membership_quantity fields to check how many items can be claimed.

Combined redemption fields

Fields can_redeem_via_package_combined, can_redeem_via_membership_combined, can_redeem_via_loyalty_points_combined will be marked as true if the client can redeem that item along with other items, when testing an entire transaction with Transaction Price Check.

Available package items will be checked first. If not enough available package items are found, then available membership inclusion items will be checked for the remaining items. If not enough available membership inclusion items are found, then loyalty points are checked for the remaining items. Only the first available claim will be included - ie. if both can_redeem_via_package and can_redeem_via_membership are true, then can_redeem_via_package_combined will be true, and can_redeem_via_membership_combined will be false, because the item has been selected for a package claim in this potential combined claim.

For a multiple quantity item, the quantity can be spread amongst different redemption types. Eg. for quantity=4, the response could contain can_redeem_via_package_quantity_combined=1, can_redeem_via_membership_quantity_combined=1, can_redeem_via_loyalty_points_combined=false, meaning that one of the four items can be claimed via package, one can be claimed via membership inclusion, and the final two items would need to be paid for.

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.

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

Sharing Update

Example Request:

curl "https://apiN.simplesalon.com/v1/product/sharing/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "product_id": 5555,
    "company_ids": 
    [
        12345,
        12346
    ],
    "share": true
  }'

Example Response:

{
    "success": true
}

Updates the sharing of a product in a Dome.

HTTP Request

POST /v1/product/sharing/update

Request Data

Parameter Type Description
product_id integer required The ID of the product to update sharing on.
company_ids integer[] required The IDs of the child companies to updating sharing on.
share boolean required Set to true to share this product with these companies. Set to false to remove sharing of this product from these companies.
replace boolean If true, any child companies not included in the company_ids list will also have their sharing updated to the opposite value of share. If false, child companies not included in the company_ids list will keep their existing sharing value for this product. Defaults to false if omitted.

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 '
  {
    "options":
    {
        ...
    }
  }'

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 Tax Rate The tax rate applied to this product. Omitted if tax_free=true.
tax_free boolean If true, this product does not have tax applied.
tax_id_override boolean The specific Tax Rate to apply to this product. If 0, the default tax_for_products rate will be applied. Omitted if tax_free=true.
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.

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.
resource_ids integer[] A list of resource IDs to filter resources by. Invalid IDs will be ignored (no error will be raised).

Roles

Special Values

System Role: Administrator

A role_id value of -1 indicates the Administrator role.

System Role: Staff

A role_id value of -2 indicates the Staff role.

System Role: Manager

A role_id value of -3 indicates the Manager role.

System Role: API Only

A role_id value of -5 indicates the API Only role.

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.

Add

Example Request:

curl "https://apiN.simplesalon.com/v1/roster/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "roster": 
    {
        "company_id": 12345,
        "duration": 30,
        "operator_id": 2222,
        "time_start": "2019-01-01T11:00:00+11:00"
    }
  }'

Example Response:

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

Adds a new roster.

HTTP Request

POST /v1/roster/add

Request Data

Parameter Type Description
roster Roster required The roster to add. Must specify roster_id. Omitted or null fields are left unchanged.
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.
time_end This field is ignored - use duration to set 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).
roster Roster The added roster.

Update

Example Request:

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

Example Response:

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

Updates an existing roster.

HTTP Request

POST /v1/roster/update

Request Data

Parameter Type Description
roster Roster required The roster to update. Must specify roster_id. Omitted or null fields are left unchanged.
Field Notes for Update
company_id This field cannot be changed.
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).
roster Roster The updated roster.

Delete

Example Request:

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

Example Response:

{
    "success": true
}

Deletes a roster.

HTTP Request

POST /v1/roster/delete

Request Data

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

Response Data

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

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 '
  {
    "filters":
    {
        ...
    }
    "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
filters RosterTypeFilter The filters to apply to the roster type 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.
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

RosterTypeFilter

Parameter Type Description
company_id integer The company ID to retrieve roster types for. If omitted, defaults to the logged in user's company ID.
roster_type_ids integer[] A list of roster type IDs to filter roster types by. Invalid IDs will be ignored (no error will be raised).

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.

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.
options.expanded_fields ExpandedField[] Available fields for expanding are: operators, service_levels.

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
operator_id integer Specifying the operator ID will apply level changes to price and duration if the operator's level has an override set. If the operator cannot perform this service, an error will be returned.

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.
operator_id integer Specifying the operator ID will apply level changes to price and duration if the operator's level has an override set. If the operator cannot perform this group service, an error will be returned.

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.

Service Level List

Example Request:

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

Example Response:

{
    "success": true,
    "service_levels": [
        {
            "duration": 30,
            "level_id": 100,
            "price": 9.00,
            "service_level_id": 1687481,
            "service_id": 3333
        },
        {
            "duration": 15,
            "level_id": 200,
            "price": 12.00,
            "service_level_id": 1687482,
            "service_id": 3333
        }
    ]
}

Returns the level pricing and duration. If no results are returned, the service always uses the base price and duration.

HTTP Request

POST /v1/service/level/list

Request Data

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

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
service_levels ServiceLevel[] The service levels for this service, with price and duration fields filled out for each.

Service Resource List

Example Request:

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

Example Response:

{
    "success": true,
    "resources": [
        {
            "company_id": 12345,
            "name": "IPL Machine",
            "description": "",
            "resource_id": 2929
        }
    ]
}

Returns the list of resources this service can use.

HTTP Request

POST /v1/service/resource/list

Request Data

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

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
services Resource[] The resources this service can use.

Sharing Update

Example Request:

curl "https://apiN.simplesalon.com/v1/service/sharing/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "service_id": 3333,
    "company_ids": 
    [
        12345,
        12346
    ],
    "share": true
  }'

Example Response:

{
    "success": true
}

Updates the sharing of a service in a Dome.

HTTP Request

POST /v1/service/sharing/update

Request Data

Parameter Type Description
service_id integer required The ID of the service to update sharing on.
company_ids integer[] required The IDs of the child companies to updating sharing on.
share boolean required Set to true to share this service with these companies. Set to false to remove sharing of this service from these companies.
replace boolean If true, any child companies not included in the company_ids list will also have their sharing updated to the opposite value of share. If false, child companies not included in the company_ids list will keep their existing sharing value for this service. Defaults to false if omitted.

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.

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.

Class

A class service is a service that multiple clients can attend at once, at the same time.
For example, a 'Yoga' class could be attended by 10 clients at the same time, with one operator as the instructor.

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.
base_duration integer The duration of the service before the operator's level was applied. This field only appears when an operator level has been applied, eg. when requesting a list of services for a specific operator, and there is a level override set for this service for the operator's level.
base_price decimal The price of the service before the operator's level was applied. This field only appears when an operator level has been applied, eg. when requesting a list of services for a specific operator, and there is a level override set for this service for the operator's level.
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 be non-zero, and a multiple of the company's appointment interval. When retrieving the service for a specific operator, this field will contain the duration for that operator, and the original duration will instead be returned in base_duration.
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_categories OnlineCategory[] The categories this service is shown in on your online booking website. Omitted if online_booking_show is false.
online_booking_name string The name of the service as displayed on your online booking website.
online_booking_price decimal The price of the service with your online booking markup applied. Omitted if online_booking_show is false. This may or may not include tax, depending on the company's prices_inc_tax setting.
online_booking_price_with_tax decimal The price of the service with your online booking markup applied including any tax. Cannot be set directly - it is calculated from the online_booking_price field.
online_booking_price_without_tax decimal The price of the service with your online booking markup applied excluding any tax. Cannot be set directly - it is calculated from the online_booking_price field.
online_booking_show boolean Whether the service is visible on your online booking website.
online_booking_tax_amount decimal The amount of tax with your online booking markup applied. Cannot be set directly - it is calculated from the online_booking_price field.
operators Operator[] The list of operators who can perform the service. Must specifically request this field via options.expanded_fields.
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. When retrieving the service for a specific operator, this field will contain the price for that operator, and the original price will instead be returned in base_price. This may or may not include tax, depending on the company's prices_inc_tax setting.
price_with_tax decimal The price of the service including any tax. Cannot be set directly - it is calculated from the price field.
price_without_tax decimal The price of the service excluding any tax. Cannot be set directly - it is calculated from the price field.
processing_duration integer The length of time for service processing, in minutes. Eg. the time it takes for a client's hair to dry - subsequent services for this client (or any client: see processing_duration_blocked) must wait until the processing time is finished. Must a multiple of the company's appointment interval.
processing_duration_blocked boolean If true, appointments (for any client) cannot be booked in the processing duration time following the appointment (however a user with a Manager level Role or higher can override this). If false, the operator can perform services on other clients during this time, but subsequent services booked for the same client will default to waiting until the processing time is finished.
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).
service_levels ServiceLevel[] The list of levels for this service. Must specifically request this field via options.expanded_fields.
tax Tax Rate The tax rate applied to this service. Omitted if tax_free=true.
tax_amount decimal The amount of tax. Cannot be set directly - it is calculated from the price field.
tax_free boolean If true, this service does not have tax applied.
tax_id_override boolean The specific Tax Rate to apply to this service. If 0, the default tax_for_services rate will be applied. Omitted if tax_free=true.

Service Level

Parameter Type Description
service_level_id integer The ID of service level.
level_id integer The ID of the operator level.
duration integer The length of time for the service at this level, in minutes. Must be non-zero, and a multiple of the company's appointment interval.
online_booking_price decimal The price of the service at this level with your online booking markup applied. Omitted if online_booking_show for the service is false. This may or may not include tax, depending on the company's prices_inc_tax setting.
online_booking_price_with_tax decimal The price of the service at this level with your online booking markup applied including any tax. Cannot be set directly - it is calculated from the online_booking_price field.
online_booking_price_without_tax decimal The price of the service at this level with your online booking markup applied excluding any tax. Cannot be set directly - it is calculated from the online_booking_price field.
online_booking_tax_amount decimal The amount of tax at this level with your online booking markup applied. Cannot be set directly - it is calculated from the online_booking_price field.
price decimal The price of the service at this level. This may or may not include tax, depending on the company's prices_inc_tax setting.
price_with_tax decimal The price of the service at this level including any tax. Cannot be set directly - it is calculated from the price field.
price_without_tax decimal The price of the service at this level excluding any tax. Cannot be set directly - it is calculated from the price field.
service_id integer The ID of the service.
tax_amount decimal The amount of tax at this level. Cannot be set directly - it is calculated from the price field.

Category

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

OnlineCategory

Parameter Type Description
category_id integer The ID of the online booking category.
name string The name of the online booking 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.
online_booking_category_id string The OnlineCategory category_id to filter by. If omitted, returns all.
online_booking_show boolean The online booking visibility 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. This will apply level changes to price and duration if the operator's level has an override set.
service_ids integer[] A list of service IDs to filter services by. Invalid IDs will be ignored (no error will be raised).

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.

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
options ListOption The options for list results (note that all settings are included - paging options are ignored).
options.expanded_fields_grouped ExpandedField[] Available fields for expanding are: discount_types, payment_types.

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).
discount_types DiscountType[] The list of discount types. Omitted if advanced_discounting is 0. Must specifically request this field via options.expanded_fields_grouped.
operators Operator[] The list of operators available at POS.
payment_types PaymentType[] The list of payment types that have show_on_pos set to true. Must specifically request this field via options.expanded_fields_grouped.
tax_combined_name string The name to use when referring to all taxes - ie. the total of all taxes at POS.
tax_for_memberships TaxRate The default tax rate to apply to memberships (excludes memberships marked tax_free, and memberships with a tax_id_override set)
tax_for_packages TaxRate The default tax rate to apply to packages (excludes packages marked tax_free, and packages with a tax_id_override set)
tax_for_products TaxRate The default tax rate to apply to products (excludes products marked tax_free, and products with a tax_id_override set)
tax_for_services TaxRate The default tax rate to apply to services (excludes services marked tax_free, and services with a tax_id_override set)
tax_for_vouchers TaxRate The default tax rate to apply to vouchers (excludes vouchers marked tax_free, and vouchers with a tax_id_override set)
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.

Online Booking List

Example Request:

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

Example Response:

{
    "success":