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.
settings Setting[] A list of settings relating to login/general use for the company.

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.
settings Setting[] A list of settings relating to login/general use for the company.

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

Global Lockout

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' \
  -H 'X-Lockout-Tokens: ZjkzN2IyZTRkYmUzNDRhMmE3ZjYwMWY3MGQyY2YwMTY=, MzM4NzBmMmE4MDFkNGFjYmEwM2QyMDlhMWIwMDgyOGI=' \
  -d '
  {
    "username":"myusername",
    "password":"mypassword",
    "company_id":12345
  }'

Global Lockout prevents users of lower level Roles from logging in to Simple Salon from unauthorised devices. For example, users will only be able to login to their account from the computer located at the company's premises, and they will not be able to login from their personal mobile phone.

When the Global Lockout setting (global_lockout_manager and/or global_lockout_staff) is enabled, an Administrator level role must specifically authorise each device they would like to allow lower level users to login on, by creating a Global Lockout Token.
To enable logins from both Manager and Staff level users on a single device, you must create a Global Lockout token for each level.

Each Login, Refresh Login or Switch User request for a company should include the X-Lockout-Tokens header, with a comma-separated list of all Global Lockout tokens matching that company ID that have been stored on this device.

Global Lockout Token Add

Example Request:

curl "https://apiN.simplesalon.com/v1/global_lockout_token/add"
  -H 'Content-Type: application/json' \
  -d '
  {
  "global_lockout_token": {
      "company_id": 12345,
      "role_id":-2,
      "device_name":"Lee iPhone",
      "device_uuid":"zyxwvu",
   }
  }'

Example Response:

{
  "success": true,
    "global_lockout_token": {
        "company_id": 12345,
        "device_name": "Lee iPhone",
        "device_uuid": "zyxwvu",
        "role_id": -2,
        "token": "MzM4NzBmMmE4MDFkNGFjYmEwM2QyMDlhMWIwMDgyOGI="
    }
}

Creates a global lockout token, allowing users of the specified role level to login using this token (ie. on this device) when global lockout settings are in force.
To enable logins from both Manager and Staff level users on a single device, you must create a Global Lockout token for each level, and send both in the X-Lockout-Tokens header with each Login, Refresh Login or Switch User request.

HTTP Request

POST /v1/global_lockout_token/add

Request Data

Parameter Type Description
global_lockout_token GlobalLockoutToken The global lockout token to add.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
global_lockout_token GlobalLockoutToken The added global lockout token.

Global Lockout Token Delete

Example Request:

curl "https://apiN.simplesalon.com/v1/global_lockout_token/delete"
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters": {
      "company_id": 12345,
      "token": "MzM4NzBmMmE4MDFkNGFjYmEwM2QyMDlhMWIwMDgyOGI="
   }
  }'

Example Response:

{
  "success": true
}

Delete the global lockout token - user roles affected by a Global Lockout setting will no longer be able to log in on this device.

HTTP Request

POST /v1/global_lockout_token/delete

Request Data

Parameter Type Description
filters.role_id integer required* The role ID of the tokens to delete - this will delete ALL tokens for ALL devices for this role_id, and can only be called by an Administrator level Role. Must specify this field or filters.token.
filters.token string required* The token field of the global lockout token - this will delete only this individual token, and can be called with just the X-Partner-Token header (ie. without a user login). Must specify this field or filters.role_id.

Response Data

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

Models

GlobalLockoutToken

Parameter Type Description
company_id integer The company ID of the global lockout token.
device_name string The display name of the device.
device_uuid string The device's unique ID.
role_id integer The role ID the global lockout token applies to.
token string The token.

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.
billing_period string The billing period. Valid values are: none, month, year. If omitted, defaults to month.
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 Transaction List

Example Request:

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

Example Response:

{
    "success": true,
     "page_number": 1,
    "rows_per_page": 10,
    "sms_transactions": [
        {
            "sms_transaction_id": 4794686,
            "amount": 50,
            "company_id": 12345,
            "credit_type": "sms",
            "date": "2019-01-01T09:00:00+11:00",
            "billing_invoice_id": 882277,
            "type": "purchase"
        }
    ]
}

Get a list of SMS transactions.

HTTP Request

POST /v1/account/sms/transaction/list

Request Data

Parameter Type Description
filters SMSTransactionFilter required The filters to apply to the SMS transaction list
options.expanded_fields ExpandedField Available fields for expanding are: billing_invoice, user.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
sms_transactions SMSTransaction[] The list of SMS transactions matching the filters.
sms_transactions_totals SMSTransaction Totals The totals of all SMS transactions matching the filters. Only returned when options.return_total is true.

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.

WhatsApp Balance

Example Request:

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

Example Response:

{
    "success": true,
    "balance": {
        "company_id": 12345,
        "credit_price": 0.25,
        "credit_type": "whatsapp",
        "currency_code": "AUD",
        "currency_symbol": "$",
        "free_credits": 14,
        "funds": 20.48,
        "settings": [
            {
                "name": "whatsapp_enabled",
                "value": "1"
            }
        ]
    }
}

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

HTTP Request

POST /v1/account/whatsapp/balance

Request Data

Parameter Type Description
company_id integer The company ID to request WhatsApp 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 WhatsApp balance data.

WhatsApp Purchase

Example Request:

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

Example Response:

{
    "success": true,
    "balance": {
        "company_id": 12345,
        "credit_type": "whatsapp",
        "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 WhatsApp credit, then returns the updated WhatsApp balance.

HTTP Request

POST /v1/account/whatsapp/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 WhatsApp credit for.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
balance SMS Balance The WhatsApp 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.

WhatsApp Quote

Example Request:

curl "https://apiN.simplesalon.com/v1/account/whatsapp/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,
        "credit_type": "whatsapp",
        "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/whatsapp/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 WhatsApp 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.

WhatsApp Transfer

Example Request:

curl "https://apiN.simplesalon.com/v1/account/whatsapp/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,
        "credit_type": "whatsapp",
        "currency_code": "AUD",
        "currency_symbol": "$",
        "free_credits": 14,
        "funds": 60.48
    },
    "sms_transaction_id": 978110,
    "destination_balance": {
        "company_id": 12346,
        "credit_type": "whatsapp",
        "currency_code": "AUD",
        "currency_symbol": "$",
        "free_credits": 0,
        "funds": 10.00
    }
}

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

HTTP Request

POST /v1/account/whatsapp/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 WhatsApp 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_period string The billing period. Valid values are: none, month, year.
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.
billing_period string The billing period for the price. Valid values are: none, month, year.
currency_code string The 3-letter ISO 4217 code of the currency of the price and credit_price.
currency_symbol string The currency symbol 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: adla (an ADLA addon), plan (the base subscription plan), sms_dedicated_number (a dedicated number for SMS addon), whatsapp_addon (a WhatsApp addon).
price decimal The price of the billing product for the billing_period.

BillingProductFilter

Parameter Type Description
billing_period string The billing period for pricing and inclusions - must also specify either company_id or country_id. Valid values are: none, month, year. If omitted and company_id is set, defaults to the billing_period of that company's subscription. Otherwise, defaults to month.
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).
credit_type string The SMS transaction credit type. Valid values are: sms, whatsapp.
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.

SMS Transaction

Parameter Type Description
sms_transaction_id integer The SMS transaction ID.
amount decimal The amount of the transaction (in funds). See also credits.
billing_invoice_id integer The ID of the related Billing Invoice - eg. when type=purchase.
billing_invoice Billing Invoice The related billing invoice - eg. when type=purchase. Must specifically request this field via ExpandedFields.
credits integer The amount of the transaction (in credits). See also amount.
credit_type string The SMS transaction credit type. Valid values are: sms, whatsapp.
company_id integer The company ID for the transaction.
date string The date of the SMS transaction. See Dates.
extra_fields ExtraField[] The list of extra fields relating to this transaction. Valid extra field keys are: from_company_id (for a type=transfer_in transaction), to_company_id (for a type=transfer_out transaction).
message_id integer The ID of the related Campaign Message - eg. when type=use.
type string The type of SMS transaction. Valid values are: estimate (an SMS send cost was estimated), use (an amount was used to send SMS), purchase (SMS funds were purchased), transfer_in (an amount was transferred in from another company), transfer_out (an amount was transferred out to another location), plan_change_reduction (free credits were removed pro-rata due to a plan change to a lower plan), plan_change_addition (free credits were added pro-rata due to a plan change to a higher plan), plan_add (free credits were added due to monthly renewal of the company's plan), refund (SMS funds were refunded), admin_add (an amount was added by the system), admin_remove (an amount was removed by the system).
user_id integer The ID of the user who performed the SMS transaction.
user User The user who performed the SMS transaction. Must specifically request this field via ExpandedFields.

SMS Transaction Totals

Parameter Type Description
amount decimal The total amount of the transactions (in funds). See also credits.
credits integer The total amount of the transactions (in credits). See also amount.

SMSTransactionFilter

Parameter Type Description
company_id integer The company ID that the SMS transaction was for.
credit_type string The SMS transaction credit type to filter by. Valid values are: sms, whatsapp.
date_min string The SMS transaction date to filter by (inclusive). See Dates.
date_max string The SMS transaction date to filter by (exclusive). See Dates.
exclude_types string[] The list of SMS transaction types to exclude. See SMS Transaction type field for valid values.
type string The type of SMS transaction. See SMS Transaction type field for valid values.
user_id integer The ID of the user that made the SMS transaction.

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. Valid values are Third Party Link Types marked as Used For: Accounting. 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. Valid values are Third Party Link Types marked as Used For: Accounting. 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. Valid values are Third Party Link Types marked as Used For: Accounting. 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.

Item List

Example Request:

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

Example Response:

{
    "success": true,    
    "items": [
        {
            "item_id": "7890",
            "name": "Sales"
        },
        ...
    ]
}

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

HTTP Request

POST /v1/third_party/accounting/item/list

Request Data

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

Response Data

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

Item Get

Example Request:

curl "https://apiN.simplesalon.com/v1/third_party/accounting/item/get"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "item_id": "7890"
  }'

Example Response:

{
    "success": true,
    "item": 
    {
        "item_id": "7890",
        "name": "Sales"
    }
}

Gets a single item.

HTTP Request

POST /v1/third_party/accounting/item/get

Request Data

Parameter Type Description
item_id integer required The ID of the item to retrieve
gateway string The accounting gateway to use. Valid values are Third Party Link Types marked as Used For: Accounting. 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).
item Item The item.

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, liabilities or equity. 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. Valid values are Third Party Link Types marked as Used For: Accounting. 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. Valid values are Third Party Link Types marked as Used For: Accounting. 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.

Item

Parameter Type Description
item_id string The ID of the item in the third party.
name string The name of the item in the third party.

ItemFilter

Parameter Type Description
company_id integer The company ID to retrieve items for. If omitted, defaults to the logged in user's company ID.
gateway string The accounting gateway to use. Valid values are Third Party Link Types marked as Used For: Accounting. If omitted, defaults to the company's default accounting gateway.

Activity Logs

List

Example Request:

curl "https://apiN.simplesalon.com/v1/activity_log/list"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "filters":
    {
      "date_created_min": "2020-01-01T12:00:00+11:00",
      "date_created_max": "2020-01-02T12:00:00+11:00",
      "item_id": 1111,
      "item_type": "client"
      ...
    },
    "options":
    {
      ...
    }
  }'

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "activity_logs": [
        {
            "activity_log_id": 1486320,
            "activity_type": "add",
            "company_id": 12345,
            "date_created": "2020-01-01T12:00:00+11:00",
            "description": "Added client - Joe Citizen",
            "item_id": 1111,
            "item_type": "client",
            "user_id": 97714
        },
        ...
    ]
}

Get a list of activity logs.

HTTP Request

POST /v1/activity_log/list

Request Data

Parameter Type Description
filters ActivityLogFilter required The filters to apply to the activity log list
options ListOptions The options for list results.
options.sort_expression string Available fields for sorting are: date_created (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.
activity_logs ActivityLog[] The list of activity logs matching the filters and page options.

Models

ActivityLogFilter

Parameter Type Description
date_created_min string required The creation date to retrieve activity logs from (inclusive).
date_created_max string required The creation date to retrieve activity logs to (exclusive).
item_type string required The type of item to retrieve activity logs for.
item_id integer required The item ID to retrieve activity logs for, eg. if item_type=client, then this field would be a client_id.
include_description_logs string If true, also includes logs with other item_type values that include the item_id in their description. If omitted, defaults to false, which only returns logs that match both item_id and item_type.

ActivityLog

Parameter Type Description
activity_log_id integer The ID of the activity log.
activity_type string The type of activity for this activity log. Valid values are: add, delete, error, get, log_in, log_in_pin, share, start, stop, unshare, update, view.
activity_type_description string The text description of the activity_type.
company_id integer The company ID of the activity log.
date_created string The date this activity log was created.
description string The description of this activity.
ip_address string The IP address where this activity request originated from.
item_id integer The ID of the item this activity log refers to.
item_type string The type of item this activity log refers to. Valid values are: appointment, client_product, client, service, brand, product, operator, transaction, roster, client_membership, api, report, account, setting_sms, setting_security, third_party, campaign, online, membership, company, user or omitted/null.
item_type_description string The text description of the item_type.
user_id integer The ID of the user this activity log refers to.
operator_id integer The ID of the operator this activity log refers to.

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.
time_start_max string The maximum time you can set for time_start_max - any dates beyond this value will always return that there are none available. If omitted, there is no limit.

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

Repeat

Example Request:

curl "https://apiN.simplesalon.com/v1/appointment/repeat"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
   "appointment_id": 56789,
   "repeat_interval_type": "weeks",
   "repeat_interval_length": 1,
   "repeat_times": 2
  }'

Example Response:

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

Repeats an appointment.
If any appointments are returned with clashed=true, the user should be prompted to review the clashed appointments (to either move them to an available timeslot or delete them).

HTTP Request

POST /v1/appointment/repeat

Request Data

Parameter Type Description
appointment_id integer required* The ID of the appointment to repeat - any child appointments will also be repeated. Must specify appointment_id or appointment_ids.
appointment_ids integer[] required* The IDs of the appointments to repeat - any child appointments will also be repeated. 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.
repeat_interval_length integer The length of time between repeated appointments, in combination with repeat_interval_type. Maximum is 7 for days, 6 for weeks, 3 for months. Defaults to 1 if omitted.
repeat_interval_type string required The length of time between repeated appointments, in combination with repeat_interval_length. Valid values are: days, weeks, months.
repeat_times integer required The number of times to repeat the appointment. For example, if repeat_interval_length=2, repeat_interval_type=weeks, and repeat_times=3, then three appointments will be made: at 2, 4 and 6 weeks from the original appointment. Maximum is 84 for days, 12 for weeks and months.
options.expanded_fields_grouped ExpandedField[] Available fields for expanding are: clients, operators, resources, services, packages.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
appointments Appointment[] The list of appointments created.
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.

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. Required unless specifying one or more of appointment_ids, claimed=false, client_id, client_package_id, parent_appointment_id, preset=pos_future, transaction_id, unconfirmed=true.
time_end string required* The date to retrieve appointments to (exclusive). Timezone offset in this field is ignored. See Dates. Required unless specifying one or more of appointment_ids, claimed=false, client_id, client_package_id, parent_appointment_id, preset=pos_future, transaction_id, unconfirmed=true.
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.
clashed boolean true to return appointments that have been marked as clashed and are awaiting a user to assign them to an available timeslot, false for all other appointments. If omitted, returns both.
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)
comments_only boolean true for appointments with comments, false for all other appointments. If omitted, returns both.
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.
include_pos_data boolean If true, returns extra fields relevant for these appointments at POS (client_id must also be specified), such as can_redeem_via_package.
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.
operator_online_booking_show boolean The operator's online booking visibility to filter by. If omitted, returns all.
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, include_pos_data is automatically true)
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.
clashed boolean true for appointments that have been marked as clashed and are awaiting a user to assign them to an available timeslot. false 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.
created_operator_id integer The operator ID of the operator who created the appointment. If set, created_user_id will be omitted.
created_operator Operator Expanded field of created_operator_id. The operator who created the appointment.
created_user_id integer The user ID of the user who created the appointment. If set, created_operator_id will be omitted.
created_user User Expanded field of created_user_id. The user who created the appointment.
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.
double_booked boolean true if the appointment is double booked, false if not.
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.
linked_appointment_id integer The ID of the appointment from a linked transaction, eg. if an appointment was refunded, the original appointment will have the refunded appointment's ID here, and vice versa.
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.
operator Operator Expanded field of operator_id. The operator 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.
refund boolean Whether this appointment was a refund.
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.
status string The status of the appointment. Currently only set when requesting a single appointment, via Appointments Get.
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 reminder 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).

Merge

Example Request:

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

Example Response:

{
    "success": true
}

Merges two clients into one.

HTTP Request

POST /v1/client/merge

Request Data

Parameter Type Description
client_id integer required The ID of the client to keep.
merge_client_id integer required The ID of the client to merge into client_id. This client will be deleted after the merge is complete.

Response Data

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

Undelete

Example Request:

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

Example Response:

{
    "success": true
}

Restores a client that has previously been deleted.

HTTP Request

POST /v1/client/undelete

Request Data

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

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.
exclude_client_ids integer[] A list of client IDs to exclude when filtering clients. Invalid IDs will be ignored (no error will be raised).
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.
today_unpaid boolean true to include only clients who have unpaid appointments today.

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.
alert_message string Important alert message for this client - if set, this alert should be shown when viewing or editing the client, and on any appointments for this client.
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.
deleted boolean If true, this client has been deleted.
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.
last_appointment_no_show boolean Whether the client's last appointment had the No Show flag set. Only included when specifically requested.
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.
whatsapp_promotions_enabled boolean Whether the client wishes to receive promotional messages via WhatsApp.
whatsapp_reminders_enabled boolean Whether the client wishes to receive reminder messages via WhatsApp.

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 Account Values

List

Example Request:

curl "https://apiN.simplesalon.com/v1/client_account_value/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_account_values": [
        {
            "client_account_value_id": 3355771,
            "amount": 30,
            "client_id": 1111,
            "company_id": 12345,
            "date": "2020-01-01T12:00:00+11:00",
            "date_created": "2020-01-01T12:00:00+11:00",
            "refund": false
            "transaction_id": 85735,
            "type": "taken"
        }
    ]
}

Get a list of client account value adjustments associated with a client.

HTTP Request

POST /v1/client_account_value/list

Request Data

Parameter Type Description
filters ClientAccountValueFilter required The filters to apply to the client account value list
options ListOptions The options for list results.
options.sort_expression string Available fields for sorting are: date (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.
client_account_values ClientAccountValue[] The list of client account values matching the filters and page options.

Get

Example Request:

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

Example Response:

{
    "success": true,
    "client_account_value": 
     {
      "client_account_value_id": 3355771,
      "amount": 30,
      "client_id": 1111,
      "company_id": 12345,
      "date": "2020-01-01T12:00:00+11:00",
      "date_created": "2020-01-01T12:00:00+11:00",
      "refund": false,
      "transaction_id": 85735,
      "type": "taken"
   }
}

Gets a single client account value adjustment.

HTTP Request

POST /v1/client_account_value/get

Request Data

Parameter Type Description
client_account_value_id integer required The ID of the client account value to retrieve

Response Data

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

Models

ClientAccountValueFilter

Parameter Type Description
client_id integer required The ID of the client to retrieve account values for.

ClientAccountValue

Parameter Type Description
client_account_value_id integer The ID of the client account value.
amount decimal The amount of the client account value.
client_id integer The ID of the client.
company_id integer The company ID of the client account value. This field is read-only.
date string The date this client account value has been charged to. If the transaction's date has been changed, date will change too, otherwise, date will be the same as date_created.
date_created string The date this client account value was created.
linked_client_account_value_id integer The ID of the client account value from a linked transaction, eg. if a client account value was refunded, the original client account value will have the refunded client account value's ID here, and vice versa.
refund boolean Whether this client account value was a refund.
transaction_id integer The ID of the transaction related to this client account value.
type string The type of the client account value. Valid values are: taken (the client increased their account balance with a payment), used (the client's account balance was charged).
type_description string The text description of the client account value type.

Client Deposits

List

Example Request:

curl "https://apiN.simplesalon.com/v1/client_deposit/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_deposits": [
        {
            "client_deposit_id": 972148,
            "amount": 30,
            "client_id": 1111,
            "company_id": 12345,
            "date_created": "2020-01-01T12:00:00+11:00",
            "refund": false
            "transaction_id": 85735,
            "type": "taken"
        }
    ]
}

Get a list of client deposits associated with a client.

HTTP Request

POST /v1/client_deposit/list

Request Data

Parameter Type Description
filters ClientDepositFilter required The filters to apply to the client deposit list
options ListOptions The options for list results.
options.sort_expression string Available fields for sorting are: date_created (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.
client_deposits ClientDeposit[] The list of client deposits matching the filters and page options.

Get

Example Request:

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

Example Response:

{
    "success": true,
    "client_deposit": 
     {
      "client_deposit_id": 972148,
      "amount": 30,
      "client_id": 1111,
      "company_id": 12345,
      "date_created": "2020-01-01T12:00:00+11:00",
      "refund": false,
      "transaction_id": 85735,
      "type": "taken"
   }
}

Gets a single client deposit.

HTTP Request

POST /v1/client_deposit/get

Request Data

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

Response Data

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

Retain

Example Request:

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

Example Response:

{
    "success": true,
    "transaction": 
     {
      "amount": 30,
      "status": "complete",
      "transaction_id": 85735,
      "type": "sale"
   }
}

Retains (forfeits) a client deposit.

HTTP Request

POST /v1/client_deposit/retain

Request Data

Parameter Type Description
client_deposit_id integer required* The ID of the client deposit to retain. Must specify either client_deposit_id or transaction_id.
transaction_id integer required* The ID of the transaction with the client deposit to retain. Must specify either client_deposit_id or transaction_id.
amount decimal The amount to retain. If omitted, retains all of the remaining amount.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
transaction Transaction The transaction where the client deposit was retained.

Models

ClientDepositFilter

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

ClientDeposit

Parameter Type Description
client_deposit_id integer The ID of the client deposit.
amount decimal The amount of the client deposit.
client_id integer The ID of the client.
company_id integer The company ID of the client deposit. This field is read-only.
date_created string The date this client deposit was created.
linked_client_deposit_id integer The ID of the client deposit from a linked transaction, eg. if a client deposit was refunded, the original client deposit will have the refunded client deposit's ID here, and vice versa.
refund boolean Whether this client deposit was a refund.
transaction_id integer The ID of the transaction related to this client deposit.
type string The type of the client deposit. Valid values are: taken, used, retained.
type_description string The text description of the client deposit type.

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/fileupload/12345/1111/abcdef.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=fileupload%40file-upload-service.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/fileupload/12345/1111/abcdef_thumb.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=fileupload%40file-upload-service.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 client files (depending on the logged in user's permissions).
options.sort_expression string Available fields for sorting are: date_created, client_file_id, specific_appointment_id+56789 (this will sort all client files with appointment_id=56789 to the top of the list). If omitted, defaults to newest first (-date_created,-client_file_id).

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/fileupload/12345/1111/abcdef.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=fileupload%40file-upload-service.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/fileupload/12345/1111/abcdef_thumb.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=fileupload%40file-upload-service.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_file 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/fileupload/01234?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=fileupload%40file-upload-service.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/fileupload/12345/1111/abcdef.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=fileupload%40file-upload-service.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/fileupload/12345/1111/abcdef_thumb.jpg?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=fileupload%40file-upload-service.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 required The ID of the client to retrieve files for.
appointment_id integer The ID of the appointment to retrieve files for.
files_only string Client files with a content_type that does not begin with image/.
images_only string Client files with a content_type that begins with image/.

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. If set, created_user_id will be omitted.
created_operator Operator Expanded field of created_operator_id. The operator who uploaded the file.
created_user_id integer The user ID of the user who uploaded the file. If set, created_operator_id will be omitted.
created_user User Expanded field of created_user_id. The user 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 Forms

List

Example Request:

curl "https://apiN.simplesalon.com/v1/client_form/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_forms": [
        {
            "client_form_id": 22745847,
            "client_id": 1111,
            "company_id": 12345,
            "date_created": "2020-01-01T12:00:00+11:00",
            "form_id": 3988877,
            "locked": false,
            "status": "created"
        }
    ]
}

Get a list of client forms associated with a client.

HTTP Request

POST /v1/client_form/list

Request Data

Parameter Type Description
filters ClientFormFilter required The filters to apply to the client form list
options ListOptions The options for list results.
options.expanded_fields ExpandedField[] Available fields for expanding are: form.

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_forms ClientForm[] The list of client forms matching the filters and page options.

Get

Example Request:

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

Example Response:

{
    "success": true,
    "client_form": 
     {
      "client_form_id": 22745847,
      "client_id": 1111,
      "company_id": 12345,
      "date_created": "2020-01-01T12:00:00+11:00",
      "form_id": 3988877,
      "locked": false,
      "status": "created"
   }
}

Gets a single client form.

HTTP Request

POST /v1/client_form/get

Request Data

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

Response Data

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

Add

Example Request:

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

Example Response:

{
    "success": true,
    "client_form": 
    {
        "client_form_id": 22745848,
        "client_id": 1111,
         "company_id": 12345,
         "date_created": "2020-01-01T12:00:00+11:00",
         "form_id": 3988878,
         "locked": false,
         "status": "created"
    }
}

Adds a new client form.

HTTP Request

POST /v1/client_form/add

Request Data

Parameter Type Description
client_form ClientForm required The client form to add. Omitted or null fields are left as default values.
media string The media to send the client form via. Valid values are: sms, whatsapp. If omitted, defaults to sms if the company has SMS enabled, or whatsapp if the company has WhatsApp enabled and SMS disabled. Ignored if send_now is omitted or false.
send_now boolean If true, the form will be sent after adding.
Field Notes for Add
client_form_id This field cannot be set.
client_id This field is required.
form_id This field is required.

Response Data

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

Update

Example Request:

curl "https://apiN.simplesalon.com/v1/client_form/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_form_id": 22745847,
    "locked": true
  }'

Example Response:

{
    "success": true,
    "client_form": 
     {
         "client_form_id": 22745847,
         "client_id": 1111,
         "company_id": 12345,
         "date_created": "2020-01-01T12:00:00+11:00",
         "form_id": 3988878,
         "locked": true,
         "status": "created"
    }
}

Updates an existing client form.

HTTP Request

POST /v1/client_form/update

Request Data

Parameter Type Description
client_form ClientForm required The client form to update. Must specify client_form_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.
form_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_form ClientForm The updated client form.

Delete

Example Request:

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

Example Response:

{
    "success": true
}

Deletes a client form.

HTTP Request

POST /v1/client_form/delete

Request Data

Parameter Type Description
client_form_id integer required The ID of the client form 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_form/send"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "client_form_id": 22745847
  }'

Example Response:

{
    "success": true
}

Sends a client form to the client.

HTTP Request

POST /v1/client_form/send

Request Data

Parameter Type Description
client_form_id integer required The ID of the client form to send
media string The media to send the client form via. Valid values are: email, sms, whatsapp. If omitted, defaults to sms if the company has SMS enabled, or whatsapp if the company has WhatsApp enabled and SMS disabled, or email if both SMS and WhatsApp are disabled.

Response Data

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

Models

ClientFormFilter

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

ClientForm

Parameter Type Description
client_form_id integer The ID of the client form.
appointment_id integer The ID of the appointment this client form relates to. This field is not required.
client_id integer The ID of the client.
comments string Any internal comments attached to the client form - these are not visible to the client.
company_id integer The company ID of the client. This field is read-only.
date_created string The date this client form was created.
form_id integer The ID of the form.
form Form The form. Must be specifically requested using expanded_fields.
locked boolean If true, this client form cannot be edited by the client.
status string The status of the client form. Valid values are: created, sent, viewed, completed.
view_answers_url string The URL to visit to view the client's completed form. Only included when status=completed.

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.
options.sort_expression string Available fields for sorting are: date, expiry_date, client_membership_id (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.
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.
cancellation_date string If status=suspended or future_cancellation=true, this field has the start date of the cancellation. Omitted if the membership is not cancelled or future_cancellation=false.
client_id integer The ID of the client the membership was sold to.
company_id integer The company ID of the client membership.
date string The date this client membership has been charged to. If the transaction's date has been changed, date will change too, otherwise, date will be the same as date_created.
date_created string The date this client membership was created.
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.
expiry_date string The expiry date of the client membership. Omitted if the client membership never expires.
future_cancellation boolean If true, this client membership is set to be cancelled on the date set in cancellation_date.
future_suspension boolean If true, this client membership is set to be suspended on the date set in suspension_date_start.
operator_id integer The ID of the operator who sold the membership.
operator Operator Expanded field of operator_id. The operator who sold the membership.
payment_type string The payment type of the client membership. Valid values are upfront and recurring.
pos_id string Your unique identifier for an unsaved client membership. Only used in the Add Transaction API call.
price decimal The setup price of the client membership.
linked_client_membership_id integer The ID of the client membership from a linked transaction, eg. if a client membership was refunded, the original client membership will have the refunded client membership's ID here, and vice versa.
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).
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.
refund boolean Whether this client membership is a refund.
start_date string The start date of the client membership.
status string The status of the client membership. Valid values are: active, cancelled, overdue (the client membership has use_direct_debit=true, and the gateway has reported that its periodic payment has failed), pending (the client membership has use_direct_debit=true, and is waiting for the client to complete the signup process, for example, agreeing to terms and conditions), suspended, unpaid (the membership has not yet been paid for).
suspension_date_start string If status=suspended or future_suspension=true, this field has the start date of the suspension. Omitted if the membership is not suspended or future_suspension=false.
suspension_date_end string If status=suspended or future_suspension=true, this field has the end date of the suspension. Omitted if the membership is not suspended or set future_suspension=false.
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_min string The charge date to retrieve client memberships from (inclusive).
date_max string The charge date to retrieve client memberships to (exclusive).
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.
linked_client_package_id integer The ID of the client package from a linked transaction, eg. if a client package was refunded, the original client package will have the refunded client package's ID here, and vice versa.
operator_id integer The ID of the operator who sold the package.
operator Operator Expanded field of operator_id. 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.
price_with_tax decimal The price of the client package including any tax. Cannot be set directly - it is calculated from the price field.
price_without_tax decimal The price of the client package excluding any tax. Cannot be set directly - it is calculated from the price field.
package Package A minimal Package object, to provide the package name.
refund boolean Whether this client package is a refund.
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 Client The client the product was sold to. Must specifically request this field via expanded_fields.
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.
linked_client_product_id integer The ID of the client product from a linked transaction, eg. if a client product was refunded, the original client product will have the refunded client product's ID here, and vice versa.
operator_id integer The ID of the operator who sold the product.
operator Operator Expanded field of operator_id. 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.
refund boolean Whether this client product is a refund.
sold_in_client_package boolean true for client products purchased as part of a package, false for all other client products.
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. Must specify either client_voucher_id or barcode.
barcode string required* The barcode of the client voucher to retrieve. Must specify either client_voucher_id or barcode.
expanded_fields ExpandedField[] Available fields for expanding are: client_voucher_items, 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).

Client Voucher Item List

Example Request:

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

Example Response:

{
    "success": true,
     "page_number": 1,
    "rows_per_page": 10,
    "client_voucher_items": [
        {
            "client_voucher_item_id": 4174,
            "quantity": 1,
            "service_id": 3333,
            "type": "service"
        },
        ...
    ]
}

Get the list of items that are included in a client voucher (when type=item on the client voucher's voucher).

HTTP Request

POST /v1/client_voucher/item/list

Request Data

Parameter Type Description
filters ClientVoucherItemFilter required The filters to apply to the client voucher item list
options ListOptions The options for list results.
options.expanded_fields ExpandedField[] Available fields for expanding are: product, service, client_voucher.

Response Data

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

Models

Client Voucher

Parameter Type Description
barcode string The barcode of the gift voucher.
can_redeem_via_package boolean If true, this client voucher 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 voucher 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 voucher 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 voucher 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 vouchers purchased as part of a package, that have not yet been collected, true for all other client vouchers.
client_voucher_id integer The ID of the client voucher.
client_id integer The ID of the client the voucher was sold to.
client_package_id integer If this client voucher 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 voucher was sold as part of a package.
client_voucher_items ClientVoucherItem[] The list of client voucher items included in the client voucher. Must be specifically requested using expanded fields.
company_id integer The company ID of the client voucher.
date string The date of this client voucher - usually the same as date_created, but can be changed if the transaction date has been changed.
date_created string The date this client voucher was created.
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.
linked_client_voucher_id integer The ID of the client voucher from a linked transaction, eg. if a client voucher was refunded, the original client voucher will have the refunded client voucher's ID here, and vice versa.
operator_id integer The ID of the operator who sold the voucher.
operator Operator Expanded field of operator_id. 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.
refund boolean Whether this client voucher is a refund.
sold_in_client_package boolean Whether the client voucher was purchased as part of a package.
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.
claimed boolean false for client vouchers purchased as part of a package, that have not yet been collected, true for all other client vouchers. If omitted, returns both.
client_id integer The client ID to retrieve client vouchers for.
client_package_expired boolean true for client vouchers purchased as part of a package that have expired, false for all other client vouchers. If omitted, returns both.
client_package_id integer The client package ID to retrieve client vouchers for, or 0 for none. (Special Note: Unlinked Client Package Items)
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.
sold_in_client_package boolean true for client vouchers purchased as part of a package, false for all other client vouchers. If omitted, returns both.
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.

ClientVoucherItem

Parameter Type Description
client_voucher_item_id integer The ID of the client voucher item.
client_voucher_id integer The ID of the client voucher.
client_voucher ClientVoucher The client voucher. Must specifically request this field via expanded_fields.
company_id integer The company ID of the client voucher item.
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_remaining integer The number of this item remaining in the client voucher.
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.

ClientVoucherItemFilter

Parameter Type Description
client_voucher_id integer required* The client voucher ID to retrieve client voucher items for. Must specify either client_voucher_id or client_id.
client_id integer required* The client ID to retrieve client voucher items for. Must specify either client_voucher_id or client_id.
all_quantity_used boolean If true, returns only client voucher inclusion items where all the quantity has been used. If false, returns only client voucher inclusion items where there is still some quantity remaining. If omitted, returns both.
company_id integer The company ID to retrieve client voucher items for.
type string The type of client voucher inclusion items to return. Valid values are product or service. If omitted, returns both.

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": "sent",
            "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": "sent",
        "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).
campaign_id integer The ID of the created campaign.
message_id integer The ID of the created message (may be empty if the message has been queued, but not yet sent).
message Message The message (may be empty if the message has been queued, but not yet sent).
recipient_id integer The ID of the created campaign recipient.

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, sms or whatsapp) will determine how the message is sent to the recipients. If a template_type is specified, and no media is specified, the message will be sent via all default methods for that template type, eg. a reminder message would be sent via SMS and Email, if both are enabled (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, sms or whatsapp) 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: reminder (requires appointment_id), reminder_second (requires appointment_id), booking_confirmation (requires appointment_id - sends to both operator and client, if enabled), confirmation (requires appointment_id - only sends to client), first_visit (requires client_id), invoice (requires transaction_id), new_client (requires client_id), client_form (requires client_form_id), voucher (requires client_voucher_id).
appointment_id integer The ID of the appointment this message relates to.
client_id integer The ID of the client to send this message to (not required if appointment_id, client_form_id or client_voucher_id are set - the message will be sent to the client linked to that item).
client_form_id string The ID of the client form this message relates to.
client_voucher_id string The ID of the client voucher to send.
media string The media type to send the campaign via. Ignored if template_id is set. Valid values are: email, sms, whatsapp.
operator_id string The ID of the operator to send this message to.
transaction_id integer The ID of the transaction this message relates to.

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, template_type or message.
template_type string required* The type of template to estimate price for. Valid values are: send_client_form. Must specify either template_id, template_type or message.
message string required* The content of the message to estimate price for. Must specify either template_id, template_type 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.

Send WhatsApp

Example Request:

curl "https://apiN.simplesalon.com/v1/send/whatsapp"
  -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 a WhatsApp message to the client's mobile number.
Note that ad-hoc WhatsApp messages can only be sent to clients that have responded to a WhatsApp message in the last 24 hours.

HTTP Request

POST /v1/send/whatsapp

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 WhatsApp Price Check

Example Request:

curl "https://apiN.simplesalon.com/v1/send/whatsapp/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,
    "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 😄"
}

Estimates the cost of a WhatsApp message.

A single WhatsApp message can be up to 4096 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/whatsapp/check

Request Data

Parameter Type Description
template_id integer required* The ID of the template to estimate price for. Must specify either template_id, template_type or message.
template_type string required* The type of template to estimate price for. Valid values are: send_client_form. Must specify either template_id, template_type or message.
message string required* The content of the message to estimate price for. Must specify either template_id, template_type or message.
client_id integer The client ID the message will be sent to - specifying this will allow us to check if the client has not sent the company a message in the last 24 hours (in which case an ad-hoc message is most likely to be rejected by WhatsApp).
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 WhatsApp 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 WhatsApp 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 WhatsApp message.
character_count_sms_used integer The number of characters in this message when sent via WhatsApp.
credits integer The estimated number of credits required to send this message to one recipient.
message string The final message used to estimate price. Company template tags will be replaced, and any characters exceeding the maximum length for a WhatsApp message 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, sms, whatsapp.
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, admin, birthday, confirmation, confirmation_with_invoice, client_form, client_membership, first_visit, invoice, no_recent_visit, one_touch_marketing, online_booking, online_booking_alert, order, reminder, reminder_second, voucher.
status string The status of this campaign. Valid values are building, pending, sending, 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 recipient_id is omitted.
date_created_max string required* The creation date to retrieve message replies to (exclusive). Required if recipient_id is omitted.
client_id integer The client ID to retrieve message replies for (when campaign.type=client).
company_id integer The company ID to retrieve message replies for.
include_sent_dlr boolean If true, will include the dlr field on each message with type=message_sent.
include_sent_reply_first boolean If true, will include the reply_first field on each message with type=message_sent.
recipient_id integer The recipient ID to retrieve message replies for.
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.
dlr Message The delivery report (if any) for this message. Omitted if type!=message_sent. Must be specifically requested via include_sent_dlr.
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.
reply_first Message The first reply (if any) for this message. Omitted if type!=message_sent. Must be specifically requested via include_sent_reply_first.
sender string The sender address.
status string The status of this message. Valid values are none, sent (sent to the messaging provider), delivered (the messaging provider has reported that the message was delivered), read (the messaging provider has reported that the message was read) and failed. Note that the status will be updated on the type=message_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 sent to the messaging provider) and send_error (errors generated before the message is sent to the messaging provider, or returned by the messaging provider when attempting to send).

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

HTTP Headers

Header Value
Content-Type required Always application/json
Authorization required 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 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.
options.expanded_fields ExpandedField[] Available fields for expanding are: settings.

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.
online_booking_latitude decimal The latitude of the country that companies were requested for. Only returned if online_booking_show=true, online_booking_search_country_code was specified, and online_booking_latitude/online_booking_latitude were not specified.
online_booking_longitude decimal The longitude of the country that companies were requested for. Only returned if online_booking_show=true, online_booking_search_country_code was specified, and online_booking_latitude/online_booking_latitude were not specified.

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

Add

Example Request:

curl "https://apiN.simplesalon.com/v1/company/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
   "step": 1,
    "company": {
      "name": "Company A",
      "contact_name": "Sally Owner",
      "email": "contactus@companyabysallyowner.com",
      "mobile":"0488777666",
      "country_code":"AU"
   }
  }'

Example Response:

{
    "success": true,
    "company": 
    {
      "name": "Company A",
      "contact_name": "Sally Owner",
      "email": "contactus@companyabysallyowner.com",
      "mobile":"0488777666",
      "country_code":"AU"
    }
}

Adds a company (depending on which step is requested).

HTTP Request

POST /v1/company/add

Request Data

Parameter Type Description
step integer required The company add step to perform. Valid values are: 1 (add company with payment information), 2 (request mobile verification code), 3 (add company with mobile verification code).
verification_token integer required The CAPTCHA verification token.
billing_item Billing Item required* The plan to sign the company up to. Required when step is 1 or 3.
company Company required* The company to add. For step=1 and step=3, must specify contact_name, email, mobile, name and country_code. For step=2, must specify mobile and country_code.
payment_token string required* The payment token to charge for this company add. Required when step=1 (except when slick=true or pending_payment=true).
verification_code integer required* The mobile verification code (sent previously from step=2). Required when step=3.
analytics_client_id string The user's Google Analytics client ID.
analytics_session_id string The user's Google Analytics session ID.
dome_company_id integer If set, this is the ID of the Dome company to link this company to.
dome_share_operators bool If true, all of the Dome's operators will be shared down to this company (if subscription plan allows). Ignored if dome_company_id is not set.
dome_share_products bool If true, all of the Dome's products will be shared down to this company. Ignored if dome_company_id is not set.
dome_share_services bool If true, all of the Dome's services will be shared down to this company. Ignored if dome_company_id is not set.
options Billing Item[] Any optional (once-off) items to purchase along with the base plan.
pending_payment bool If true, the company will request payment at first login.
promo_code string The promotion code for this company add.
referral_code string The referral code for this company add.
slick boolean If true, this is a Slick company add.
server_id integer If set, this company will be added to this specific server.
sms_opt_in bool If true, the company has explicitly opted in to receive SMS from Simple Salon.
third_party_data string The third party, 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.
verification_code_media string The media to send the mobile verification code via. Valid values are: sms, whatsapp. If omitted, defaults to sms. Ignored if step is not 2.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
company Company The company (if step is 1 or 3).
mobile string The full mobile number the verification code was sent to, including country code (if step is 2).
redirect_to string The third party URL to redirect back to, if this was a signup from a third party.

Category List

Example Request:

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

Example Response:

{
    "success": true,
    "online_booking_categories": [
        {
            "key": "hair",
            "name": "Hair"
          },
        ...
    ]
}

Get a list of company categories. Always returns all categories.

HTTP Request

POST /v1/company/category/list

Response Data

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

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_categories CompanyCategory[] The selected online booking categories for this company.
online_booking_company_id integer The company's online booking store ID.
online_booking_favourite boolean Whether the company is a favourite of the specified Online Booking client. Requires the X-Online-Booking-Client-Token HTTP Header to be specified in the request.
online_booking_search_distance decimal The distance in kilometres from the search location. Only included when a search location (online_booking_latitude/online_booking_longitude or online_booking_search_country_code) has been provided in the request.
phone string The telephone number of the company.
settings Setting[] The list of settings for this company. Must be specifically requested using expanded_fields.
status string The status of this company. Valid values are: active, closed, closed_permanently, free_trial, free_trial_ended, on_hold, pending_suspension, suspended.
status_end_date string If status is free_trial, on_hold or pending_suspension, this field has the date that the company will change to free_trial_ended, active or suspended, respectively.
website string The website address of the company.

CompanyCategory

Parameter Type Description
key string The ID key of the online booking company category.
name string The name of the online booking company category.

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_category_keys string[] The ID keys of online booking categories to filter by. If multiple categories are specified, companies matching any of the specified categories will be returned. Must also specify online_booking_show=true, and both online_booking_latitude and online_booking_longitude or online_booking_search_country_code.
online_booking_favourite boolean Returns companies that are favourites of the specified Online Booking client (requires the X-Online-Booking-Client-Token HTTP Header to be specified in the request). Ignored if online_booking_show is not true. Fields online_booking_category_keys, online_booking_latitude, online_booking_longitude, online_booking_search_radius, online_booking_search_country_code are ignored if this field is specified.
online_booking_latitude decimal The geographic latitude of the place to search for online booking companies. Must also specify online_booking_longitude, and online_booking_show=true.
online_booking_longitude decimal The geographic longitude of the place to search for online booking companies. Must also specify online_booking_latitude, and online_booking_show=true.
online_booking_search_radius decimal The radius to search around the specified online_booking_latitude/online_booking_longitude or online_booking_search_country_code. If omitted, searches 1km, expands to 5km if none found, expands to 10km if none found, then returns the nearest location regardless of distance if none found within 10km. Must also specify online_booking_show=true, and both online_booking_latitude and online_booking_longitude or online_booking_search_country_code.
online_booking_search_country_code string The 2-letter ISO 3166-1 code of the country, if you cannot get an exact online_booking_latitude and online_booking_longitude (ie. if GPS permission is denied). Must also specify online_booking_show=true. The online_booking_latitude and online_booking_longitude of that country will be returned.
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",
            "display_priority": 100,
            "name": "Australia",
            "currency_symbol": "$",
            "currency_code": "AUD",
            "phone_prefix": 61,
            "sms_opt_in_required": false
        },
        ...
    ]
}

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.
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.
display_priority integer The priority to display the country in - a higher number indicates the country should appear first. When display_priority is equal, order alphabetically by name.
name string The country's name.
phone_prefix integer The default telephone prefix of the country.
sms_opt_in_required boolean If true, SMS Opt In must be shown for this country before enabling any SMS features. For example, if your integration allows a new Client to sign up via a web form, explicit consent for SMS must be obtained before setting sms_reminders_enabled or sms_promotions_enabled to true.

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

End of Session

Get

Example Request:

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

Example Response:

{
    "success": true,
    "end_of_session": 
    {
      "cash_to_deposit": 0.00,
      "closed": false,
      "company_id": 12345,
      "end_of_session_date": "2019-01-01T17:00:00+11:00",
      "end_of_session_id": 808877,
      "next_session_float": 0.00
  }
}

Gets a single end of session.

HTTP Request

POST /v1/end_of_session/get

Request Data

Parameter Type Description
end_of_session_id integer required* The ID of the end of session to retrieve. Must specify either end_of_session_id or today=true.
today boolean required* If true, retrieves the session for the company's current date. Must specify either end_of_session_id or today=true.
company_id integer The ID of the company to retrieve today's end of session from. If omitted, defaults to the logged in user's company ID. Ignored if end_of_session_id is specified.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
end_of_session EndOfSession The end of session.

Add

Example Request:

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

Example Response:

{
    "success": true,
    "end_of_session": 
    {
        "cash_to_deposit": 0.00,
      "closed": false,
      "company_id": 12345,
      "end_of_session_date": "2019-01-01T17:00:00+11:00",
      "end_of_session_id": 808877,
      "next_session_float": 0.00
    }
}

Adds a new end of session.

HTTP Request

POST /v1/end_of_session/add

Request Data

Parameter Type Description
end_of_session EndOfSession required The end of session to add.
Field Notes for Add
end_of_session_id This field must be omitted.
end_of_session_date Defaults to today if omitted.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
end_of_session EndOfSession The new end of session.

Update

Example Request:

curl "https://apiN.simplesalon.com/v1/end_of_session/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "end_of_session": 
    {
        "end_of_session_id": 808877,
        "cash_to_deposit": 30.00,
      "closed": true,
        "next_session_float": 200.00,
    }
  }'

Example Response:

{
    "success": true,
    "end_of_session": 
    {
        "cash_to_deposit": 0.00,
      "closed": false,
      "company_id": 12345,
      "end_of_session_date": "2019-01-01T17:00:00+11:00",
      "end_of_session_id": 808877,
      "next_session_float": 200.00
    }
}

Updates an (unfinished) end of session.

HTTP Request

POST /v1/end_of_session/update

Request Data

Parameter Type Description
end_of_session EndOfSession required The end of session to update. Must specify end_of_session_id. Omitted or null fields are left unchanged.
Field Notes for Update
end_of_session_id This field cannot be changed.
company_id This field cannot be changed.
end_of_session_date This field cannot be changed.
end_of_session_items This field cannot be changed.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
end_of_session EndOfSession The updated end of session.

Delete

Example Request:

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

Example Response:

{
    "success": true
}

Deletes an (unfinished) end of session.

HTTP Request

POST /v1/end_of_session/delete

Request Data

Parameter Type Description
end_of_session_id integer required The ID of the end of session to delete

Response Data

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

Item List

Example Request:

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

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "end_of_session_items": [
        {
            "amount_expected": 222.15,
            "comments": "",
            "count": 3,
            "end_of_session_id": 808877,
            "end_of_session_item_id": 5924554,
            "payment_type": {
                "name": "Cash",
                "payment_type_id": 1
            },
            "payment_type_id": 1
        },
        ...
    ]
}

Get a list of end of session items.

HTTP Request

POST /v1/end_of_session_item/list

Request Data

Parameter Type Description
filters EndOfSessionItemFilter The filters to apply to the end of session item list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all end of session items.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
end_of_session_items EndOfSessionItem[] The list of end of session items.

Item Update

Example Request:

curl "https://apiN.simplesalon.com/v1/end_of_session_item/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
     "end_of_session_item": 
    {
         "amount_actual": 232.15,
         "comments": "Found an extra $10 on shop floor",
         "end_of_session_item_id": 5924554
     }
  }'

Example Response:

{
    "success": true,
    "end_of_session_item": 
    {
         "amount_actual": 232.15,
         "amount_expected": 222.15,
         "comments": "Found an extra $10 on shop floor",
         "count": 3,
         "end_of_session_id": 808877,
         "end_of_session_item_id": 5924554,
         "payment_type": {
             "name": "Cash",
             "payment_type_id": 1
         },
         "payment_type_id": 1
     }
}

Updates an end of session item.

HTTP Request

POST /v1/end_of_session_item/update

Request Data

Parameter Type Description
end_of_session_item EndOfSessionItem required The end of session item to update. Must specify end_of_session_item_id. Omitted or null fields are left unchanged.
Field Notes for Update
end_of_session_item_id This field cannot be changed.
amount_expected This field cannot be changed.
amount_difference This field cannot be changed.
count This field cannot be changed.
payment_type_id This field cannot be changed.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
end_of_session_item EndOfSessionItem The updated end of session item.

Models

End of Session

Parameter Type Description
end_of_session_id integer The ID of the end of session.
cash_to_deposit decimal The amount of cash to deposit at the bank once the session is closed.
closed boolean Whether this session has been closed.
company_id integer The company ID of the end of session.
end_of_session_date string The date of this end of session. See Dates.
end_of_session_items EndOfSessionItem[] The list of end of session items.
next_session_float decimal The amount of cash to keep in the drawer for the next session.

End of Session Item

Parameter Type Description
end_of_session_item_id integer The ID of the end of session item.
amount_actual decimal The amount of this payment method.
amount_difference decimal The difference between the expected amount and actual amount (amount_actual - amount_expected). This field is read-only. Omitted if amount_actual has not yet been set.
amount_expected decimal The amount of this payment method expected.
comments string The comments, for when the amount_expected does not equal amount_actual.
count integer The number of transactions of this payment type.
end_of_session_id integer The ID of the end of session.
payment_type_id integer The ID of the payment type.
payment_type PaymentType The payment type.

EndOfSessionItemFilter

Parameter Type Description
end_of_session_id integer required The end of session ID to retrieve end of session items for.

Forms

List

Example Request:

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

Example Response:

{
    "success": true,
     "page_number": 1,
    "rows_per_page": 10,
    "forms": [
        {
            "auto_lock": false,
            "company_id": 12345,
            "date_created": "2020-01-01T12:00:00+11:00",
            "form_id": 3988877,
            "name": "New Client Form"
        }
    ]
}

Get a list of forms.

HTTP Request

POST /v1/form/list

Request Data

Parameter Type Description
filters FormFilter required The filters to apply to the form 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).
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.
forms Form[] The list of forms matching the filters and page options.

Get

Example Request:

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

Example Response:

{
    "success": true,
    "form": 
     {
         "auto_lock": false,
         "company_id": 12345,
         "date_created": "2020-01-01T12:00:00+11:00",
         "form_id": 3988877,
         "name": "New Client Form"
     }
}

Gets a single form.

HTTP Request

POST /v1/form/get

Request Data

Parameter Type Description
form_id integer required The ID of the form to retrieve

Response Data

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

Add

Example Request:

curl "https://apiN.simplesalon.com/v1/form/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "form": {
      "name": "Allergy screening"
    }
  }'

Example Response:

{
    "success": true,
    "form": 
     {
         "auto_lock": false,
         "company_id": 12345,
         "date_created": "2020-01-01T12:00:00+11:00",
         "form_id": 3988878,
         "name": "Allergy screening"
     }
}

Adds a new form.

HTTP Request

POST /v1/form/add

Request Data

Parameter Type Description
form Form required The form to add. Omitted or null fields are left as default values.

Response Data

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

Update

Example Request:

curl "https://apiN.simplesalon.com/v1/form/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "form_id": 3988877,
    "auto_lock": true
  }'

Example Response:

{
   "success": true,
   "form": 
    {
        "auto_lock": true,
      "company_id": 12345,
      "date_created": "2020-01-01T12:00:00+11:00",
      "form_id": 3988877,
      "name": "New Client Form"
    }
}

Updates an existing form.

HTTP Request

POST /v1/form/update

Request Data

Parameter Type Description
form Form required The form to update. Must specify form_id. Omitted or null fields are left unchanged.

Response Data

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

Delete

Example Request:

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

Example Response:

{
    "success": true
}

Deletes a form.

HTTP Request

POST /v1/form/delete

Request Data

Parameter Type Description
form_id integer required The ID of the form to delete

Response Data

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

Template List

Example Request:

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

Example Response:

{
    "success": true,
     "page_number": 1,
    "rows_per_page": 10,
    "form_templates": [
        {
            "form_template_id": 3988877,
            "name": "New Client Form Template",
            "description": "A form for collecting extra details from new clients",
            "created_by": "Simple Salon"
        }
    ]
}

Get a list of form templates.

HTTP Request

POST /v1/form/template/list

Request Data

Parameter Type Description
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).
page_number integer The page number of these results
rows_per_page integer The number of rows per page. You can set rows_per_page: -1 to return all.
total_rows integer The total number of rows matching your filters. Only returned if options.return_total is true in the request.
form_templates FormTemplate[] The list of form templates matching the page options.

Models

FormFilter

Parameter Type Description
company_id integer The ID of the company to retrieve forms for.

Form

Parameter Type Description
form_id integer The ID of the form.
auto_lock boolean If true, Client Forms will be set to locked=true once completed.
company_id integer The company ID of the form. This field is read-only.
date_created string The date this form was created.
edit_url string The URL to visit to edit the form.
name string The name of the form.
preview_url string The URL to visit to preview the form the client will see.

Form Template

Parameter Type Description
form_template_id integer The ID of the form template. Note that system form template IDs may not be unique when compared to non-system form template IDs.
created_by string The name of the company who created the form template.
description string A description of the form template.
name string The name of the form template.
preview_url string The URL to visit to preview the form template.
is_system boolean true if the form template is a system template, or false if the form template is a template created by a Dome company.

Item Files

List

Example Request:

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

Example Response:

{
    "success": true,
    "page_number": 1,
    "rows_per_page": 10,
    "item_files": [
        {
            "item_file_id": 87294,
            "type": "product",
            "display_order": 0,
            "product_id": 5555,
            "company_id": 12345,
            "content_type": "image/jpeg",
            "date_created": "2020-01-01T12:00:00+11:00",
            "display_filename": "ShampooBottle.jpg",
            "storage_filename": "https://storage.googleapis.com/ss-content-public/12345/product/5555/abcdef.jpg",
            "storage_thumbnailfilename": "https://storage.googleapis.com/ss-content-public/12345/product/5555/abcdef_thumb.jpg"
        }
    ]
}

Get a list of files associated with an item.

HTTP Request

POST /v1/item_file/list

Request Data

Parameter Type Description
filters ItemFileFilter required The filters to apply to the item file list
options ListOptions The options for list results. Note that rows_per_page can be -1 to retrieve all item files (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.
item_files ItemFile[] The list of item files matching the filters and page options.

Get

Example Request:

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

Example Response:

{
    "success": true,
    "item_file": 
    {
        "item_file_id": 87294,
         "type": "product",
         "display_order": 0,
         "product_id": 5555,
         "company_id": 12345,
         "content_type": "image/jpeg",
         "date_created": "2020-01-01T12:00:00+11:00",
         "display_filename": "ShampooBottle.jpg",
         "storage_filename": "https://storage.googleapis.com/ss-content-public/12345/product/5555/abcdef.jpg",
         "storage_thumbnailfilename": "https://storage.googleapis.com/ss-content-public/12345/product/5555/abcdef_thumb.jpg"
    }
}

Gets a single item file.

HTTP Request

POST /v1/item_file/get

Request Data

Parameter Type Description
item_file_id integer required The ID of the item file to retrieve

Response Data

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

Add

Example Request:

curl "https://apiN.simplesalon.com/v1/item_file/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "item_file":
    {
     "type": "product",
      "item_id": 5555,
     "display_order": 1,
      "display_filename": "ShampooBottleRear.jpg"
    },
    "replace": true
  }'

Example Response:

{
    "success": true,
    "item_file": 
    {
        "item_file_id": 87295,
         "type": "product",
         "display_order": 1,
         "product_id": 5555,
         "company_id": 12345,
         "content_type": "image/jpeg",
         "date_created": "2020-01-01T12:00:00+11:00",
         "display_filename": "ShampooBottleRear.jpg",
        "storage_filename": "https://storage.googleapis.com/ss-content-public/12345/product/5555/abcdef.jpg",
         "storage_thumbnailfilename": "https://storage.googleapis.com/ss-content-public/12345/product/5555/abcdef_thumb.jpg"
    }
}

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

HTTP Request

POST /v1/item_file/add

Request Data

Parameter Type Description
item_file ItemFile required The item file to add. Omitted or null fields are left as default values.
replace boolean If true, any other item files matching this type, *_id and display_order will be deleted (once the file is uploaded successfully). Defaults to false.
Field Notes for Add
item_file_id This field cannot be set.
type This field is required, along with the matching ID field (eg. if type=brand then brand_id 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).
item_file ItemFile The added item file awaiting upload.

Complete the Upload

Create a binary PUT request to the provided upload_url (from the Add Item 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 item's list of files.

Update

Example Request:

curl "https://apiN.simplesalon.com/v1/item_file/update"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "item_file_id": 87294,
    "display_filename": "ShampooBottleFront.jpg"
  }'

Example Response:

{
    "success": true,
    "item_file": 
    {
        "item_file_id": 87294,
         "type": "product",
         "display_order": 0,
         "product_id": 5555,
         "company_id": 12345,
         "content_type": "image/jpeg",
         "date_created": "2020-01-01T12:00:00+11:00",
         "display_filename": "ShampooBottleFront.jpg",
         "storage_filename": "https://storage.googleapis.com/ss-content-public/12345/product/5555/abcdef.jpg",
         "storage_thumbnailfilename": "https://storage.googleapis.com/ss-content-public/12345/product/5555/abcdef_thumb.jpg"
    }
}

Updates an existing item file.

HTTP Request

POST /v1/item_file/update

Request Data

Parameter Type Description
item_file ItemFile required The item file to update. Must specify item_file_id. Omitted or null fields are left unchanged.
Field Notes for Update
type This field cannot be changed, neither can the corresponding ID field (eg. if type=brand then brand_id 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).
item_file ItemFile The updated item file.

Delete

Example Request:

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

Example Response:

{
    "success": true
}

Deletes an item file.

HTTP Request

POST /v1/item_file/delete

Request Data

Parameter Type Description
item_file_id integer required The ID of the item file to delete

Response Data

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

Models

ItemFileFilter

Parameter Type Description
item_file_ids integer[] required* The IDs of the item files to retrieve. Must include either item_file_ids or type.
type string required* The type of item to retrieve files for. See ItemFile for valid values. An item ID field is also required. Must include either item_file_ids or type.
brand_id integer required* The ID of the Brand to retrieve files for. Required if type=brand.
category_id integer required* The ID of the Category to retrieve files for. Required if type=category.
membership_id integer required* The ID of the Membership to retrieve files for. Required if type=membership.
operator_id integer required* The ID of the Operator to retrieve files for. Required if type=operator.
package_id integer required* The ID of the Package to retrieve files for. Required if type=package.
product_id integer required* The ID of the Product to retrieve files for. Required if type=product.
service_id integer required* The ID of the Service to retrieve files for. Required if type=service.
voucher_id integer required* The ID of the Voucher to retrieve files for. Required if type=voucher.
display_order integer The specific display_order to retrieve item files for - for example, retrieve the Main image for the item by sending 0.
images_only string Item files with a content_type that begins with image/.
files_only string Item files with a content_type that does not begin with image/.
main_image boolean If true, this filter returns the Main image for the item (the one with display_order=0). Additionally, if a Main image is not set for this item, this filter will check the item's brand/category for its Main image as a fallback instead. Requires type and an item ID field set.

ItemFile

Parameter Type Description
item_file_id integer The ID of the item file.
brand_id integer The ID of the Brand, if type=brand.
category_id integer The ID of the Category, if type=category.
company_id integer The company ID of the item. This field is read-only.
content_type string The content type of the item file.
created_operator_id integer The operator ID of the operator who uploaded the file. If set, created_user_id will be omitted.
created_operator Operator Expanded field of created_operator_id. The operator who uploaded the file.
created_user_id integer The user ID of the user who uploaded the file. If set, created_operator_id will be omitted.
created_user User Expanded field of created_user_id. The user who uploaded the file.
date_created string The date this item 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.
display_order integer The order to display this item file - from lowest to highest. The Main image for the item has display_order=0. Only one item file can have display_order=0 for each type and *_id combination - if an item file is added/updated with display_order=0, any other item files for that item that have display_order=0 will be automatically updated to display_order=1.
membership_id integer The ID of the Membership, if type=membership.
operator_id integer The ID of the Operator, if type=operator.
package_id integer The ID of the Package, if type=package.
product_id integer The ID of the Product, if type=product.
service_id integer The ID of the Service, if type=service.
voucher_id integer The ID of the Voucher, if type=voucher.
storage_filename string The path to display the file. 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.
type string The type of item this file is for. Valid values are: brand, category, membership, operator, package, product, service, voucher.
upload_url string This field is only visible for an item 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.

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.

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.
Poll Transaction Get until you see a payment processed with the same amount and gateway (that does not match a payment_id you've already seen, eg. if there are two payments of the same amount through the same gateway, save the payment_id against the first payment once it's processed, then when waiting for any subsequent payments, make sure they don't have the same payment_id).

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 (via Stripe Terminal Server-driven integration):

Use a hardware terminal to take card payments in person (via Stripe Terminal local SDK):

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. Only required if using a local Stripe Terminal SDK for connection.

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.
client_secret The client secret of the payment intent created in Stripe, to use with a local Stripe Terminal SDK.

Terminal Step 3

Capture a Payment Intent.

Request Fields Value
mode terminal
step 3
barcode The payment intent ID created in Step 2 or Step 4, 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.

Terminal Step 4

Create a Payment Intent for the transaction and send it to the specified Terminal.

Request Fields Extra Fields Value
mode terminal
step 4
extra_fields terminal_id The external_id of the Stripe terminal to send the payment request to.
Response Fields Extra Fields Value
extra_fields payment_intent_id The payment intent ID that is awaiting a payment to be linked to it (eg. via swiping/inserting/tapping a card on the specified terminal).

Payment is processed automatically once the card is swiped/inserted/tapped on the reader, do not call Add Payment.

Terminal Step 5

Present a test card to the specified Terminal. This step will not work in the live environment.

Request Fields Extra Fields Value
mode terminal
step 5
extra_fields terminal_id The external_id of the Stripe terminal to send the payment request to.
test_card_number The Stripe test card number to use, to test different scenarios.
Response Fields Extra Fields Value
extra_fields status The status of the Stripe payment intent.

Terminal Step 6

Present a test card to the specified Terminal. This step will not work in the live environment.

Request Fields Extra Fields Value
mode terminal
step 6
extra_fields terminal_id The external_id of the Stripe terminal to send the payment request to.
test_card_number The Stripe test card number to use, to test different scenarios.

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.
gateway string The Live Payment Gateway this terminal is linked to. Valid values are Third Party Link Types marked as Used For: Payment Type.
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.
options.expanded_fields ExpandedField[] Available fields for expanding are: item_file_main.

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

Response Data

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

Add

Example Request:

curl "https://apiN.simplesalon.com/v1/membership/add"
  -H 'Authorization: Bearer abcdef' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "membership": 
    {
        "expiry_type": "never",
        "name": "1 Year Upfront",
        "payment_type": "upfront",
        "setup_fee": 100.00
    }
  }'

Example Response:

{
    "success": true,
    "membership": 
     {
          "expiry_type": "never",
        "membership_id": 4646,
        "name": "1 Year Upfront",
        "payment_type": "upfront",
        "setup_fee": 100.00
     }
}

Adds a new membership.

HTTP Request

POST /v1/membership/add

Request Data

Parameter Type Description
membership Membership required The membership to add.
Field Notes for Add
membership_id This field must be omitted.

Response Data

Parameter Type Description
success boolean true if the request succeeded, false if it failed (see Errors).
membership Membership The new 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).
memberships Membership[] The list of child memberships that were shared by this call. (Note: if you have set share=false and replace=true, you will get a list of the child memberships for all the other companies in the Dome).

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.
item_file_main ItemFile The Main image for this membership. Must specifically request this field via options.expanded_fields.
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.
reciprocal_rights boolean If true, the membership can be used at any location within a Dome. If false, the membership must be used at the location it was purchased. Omitted if the company is not part of a Dome.
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
client_id integer The client ID to filter by - if set, only memberships that this client has had previously (and paid for), or is having today (paid or unpaid), will be returned.
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.

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

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

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.
item_file_main ItemFile The Main image for this operator. Must specifically request this field via options.expanded_fields.
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, resources or snapshot.
whatsapp_appointment_updates_enabled boolean Whether the operator wishes to receive appointment update messages via WhatsApp.

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

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

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).
packages Package[] The list of child packages that were shared by this call. (Note: if you have set share=false and replace=true, you will get a list of the child packages for all the other companies in the Dome).

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.
description string The description of the package.
dome_package_id integer The ID of the package in the Dome.
item_file_main ItemFile The Main image for this package. Must specifically request this field via options.expanded_fields.
loyalty_points_earned integer The amount of loyalty points earned from purchasing this package.
name string The name of the package.
online_booking_price decimal The price of the package when purchased online. Omitted if online_booking_show is false.
online_booking_show boolean Whether the package is visible on your online booking website.
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
client_id integer The client ID to filter by - if set, only packages that this client has had previously (and paid for), or is having today (paid or unpaid), will be returned.
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.
online_booking_show boolean The online booking visibility to filter by. 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.
can_be_updated_from boolean true for payment types that are allowed to have their payment type changed after a transaction has been completed, false for payment types that are not. If omitted, returns both.
can_be_updated_to boolean true for payment types that are a valid option for changing a payment type after a transaction has been completed, 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.
cash_rounding boolean Whether this payment type should have cash rounding applied at POS.
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. Must specify either client_id or deposit_transaction_id.
deposit_transaction_id integer required* The ID of the deposit transaction to load. Must specify either client_id or deposit_transaction_id.
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. Ignored if deposit_transaction_id is set.
client_membership_ids integer[] The IDs of the client memberships to retrieve. If omitted, returns all unpaid client memberships for the client. Ignored if deposit_transaction_id is set.
client_package_ids integer[] The IDs of the client packages to retrieve. If omitted, returns all unpaid client packages for the client. Ignored if deposit_transaction_id is set.
client_product_ids integer[] The IDs of the client products to retrieve. If omitted, returns all unpaid client products for the client. Ignored if deposit_transaction_id is set.
expanded_fields ExpandedField[] Available fields for expanding are: appointments.operator, client_memberships.operator, client_packages.operator, client_products.operator, client_vouchers.operator.

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