SimpleSpa Documentation
Back to SimpleSpa
  • SimpleSpa Documentation
  • Scheduling Software
    • What is Scheduling Software
    • What is Salon Software
    • What is Spa Software
    • What is Medical Scheduling Software
    • What is Medi-Spa Scheduling Software
    • What is Microblading Software
  • Guides
    • General
    • Adding your first Service/Staff
    • Creating your first Appointment
    • Creating your first Transaction/Checking out a Client
  • Fundamentals
    • Dashboard
      • Overview
      • Viewing Appointments
      • Viewing Transactions
      • Making a Sale
      • Birthdays
    • Appointments
      • Calendar
      • Creating an Appointment
      • Appointment Status
      • Appointment Notes
      • Appointment Checkout
      • Creating a Block
      • Cloning a Block
    • POS
      • Recording a Sale
      • Balances & Deposits
      • Multiple Payment Methods
      • Processing Credit Cards
      • PCI Compliance
      • Common Checkouts & Tutorial Walkthroughs
        • Accepting Multiple Payments
        • Using Gift Certificates in Checkout
        • Accepting Appointment Deposits
        • Adding a Balance to a client
        • Assigning Staff during Checkout
        • Prompting and Collecting Tips
        • Applying Discounts during Checkout
        • Applying Notes & Change Calculator
    • Hardware
      • Receipt Printing
      • Thermal Receipt
      • Receipt Printer Setup
      • Cash drawer / Till
      • POS Terminal
    • Staff
      • Managing Staff
      • Fields and Settings
      • Calendar
      • Commissions Tab
      • Weekly Schedule Tab
      • Block Hours on Calendar
      • Breaks Tab
      • Clock In/Out Tab
      • How to Clock In/Out
      • Assigning Specialties
      • Staff Login
    • Clients
      • Managing Clients
      • Files
      • Images
      • Notes
      • Appointments
      • Transactions
      • Packages
      • Forms
    • Services
      • Managing Services
      • Fields and Service Settings
      • Adding Form(s) to Services
      • Assigning Resources to a Service
    • Products
      • Managing Products
      • Fields and Products Settings
      • Assign Tax Rate to all Products
      • Inventory
      • Orders
      • Vendors
    • Gift Cards
      • Gift Cards & Gift Certificates
      • Selling Gift Cards/Certificates
      • Sending Gift Cards/Certificates
      • Using Gift Cards/Certificates
      • Reloading Gift Cards/Certificates
      • Viewing Balance Gift Cards/Certificates
      • Viewing History Gift Cards/Certificates
      • Apple Wallet
    • Packages
      • Managing Packages
      • Selling Packages
      • Redeeming Packages
      • Manually Adjusting Clients Package Balance
      • Memberships
    • Forms
      • Managing Forms
      • Additional Settings
      • Additional Questions (Form Editor)
      • Assigning to a Service
      • Sending a Form
    • Users
      • Manage Users
      • User Roles
      • User Password
    • Discounts
      • Managing Discounts
      • Applying Discounts
    • Expenses
      • Managing Expenses
    • Online Booking
      • Your Custom Booking URL
      • Multiple Bookings
      • Accepting Deposits for Bookings
      • Linking & Embedding Online Booking
      • Adding a Holiday
      • Waitlist
    • Notifications
      • Email Notifications
      • SMS/Text Notifications
    • Marketing
      • Campaigns
      • Creating a New Campaign
      • Image Campaign
      • AI Campaign Generator
    • Mobile Device Support
      • iOS (iPhone & iPad)
      • Android
    • Browser Support
  • Extras
    • Video Walkthroughs
      • Creating your first appointment
      • Using the POS & completing an appointment
      • Making a sale without an appointment
      • Demo Walkthrough
    • FAQ
      • Is there anything to install?
      • Can I import my existing data to SimpleSpa?
      • How much does SimpleSpa cost?
      • Where can I get a SimpleSpa perpetual license?
      • How do I convert my SimpleSpa free trial to a paid subscription?
      • What kind of computer do I need?
      • What countries do you support?
      • How can I view the timestamp an appointment was created?
      • Do I need to download updates to my computer?
      • Does SimpleSpa have online booking?
      • Is online booking in my language?
      • How does SimpleSpa handle double booking for online appointments?
      • Does SimpleSpa send appointment reminders?
      • Does SimpleSpa send SMS/Text reminders?
      • How much does SMS/Text Notifications cost?
      • How can I add SMS/Text Notifications to my account?
      • Are the SimpleSpa Marketing Tools included in my plan?
      • I am already paying for SMS Notifications is SMS Marketing included in my package?
      • What businesses can use SimpleSpa?
      • Can I brand SimpleSpa with my logo?
      • Can I process Credit Cards with SimpleSpa?
      • What type of Credit Card Integration does SimpleSpa Support?
      • How can I disable Credit Card Auto-fill in Chrome?
      • Do plans have a minimum contract?
      • Can I downgrade my plan?
      • I am trying to login but it is redirecting to SimpleSpa.com
      • Does SimpleSpa Support Parallel Bookings
      • Does SimpleSpa support multiple business locations?
      • My online booking hours show different availability than what I have set in the staff page
      • I am a third party processor/reseller, can I work with SimpleSpa?
      • My staff will work on a different schedule on a specific date, can SimpleSpa handle this?
      • My online booking is not showing availability although I am available in my calendar
      • SimpleSpa HIPAA
      • How does SimpleSpa transmit data securely?
      • How is the data on the SimpleSpa network protected?
      • Can you provide me with more information about your data centers?
      • SimpleSpa iOS
  • API
    • SimpleSpa Enterprise API
      • Appointment Endpoint
      • Client Endpoint
      • Service Endpoint
      • Staff Endpoint
      • Ideas & Inspiration
      • Integrations
        • Zapier
        • Make.com
        • OpenAI
        • OpenAI & Cron Jobs
        • Ideas: Marketing Campaigns with Zapier, Make.com, Integrately
Powered by GitBook
On this page
  • Overview
  • Endpoint
  • Authentication
  • Request Method
  • Request Parameters
  • Example CURL Request
  • Example GET Request (Zapier/Make.com Friendly)
  • Response Format
  • Example Response
  • Example: Birthday Search
  • Response Format
  • Other Examples
  • We Miss You Campaign
  • Response Fields
  • Ideas for Marketing or Automation
  • Notes
  1. API
  2. SimpleSpa Enterprise API

Client Endpoint

Clients API access is read-only

Overview

The Clients API endpoint allows you to fetch client records from your SimpleSpa account, with powerful filtering options.

Enterprise Feature: This API access is only available to Enterprise accounts.

You can search, filter by dates, and filter by number of completed visits, allowing highly targeted client lists for marketing campaigns, automations, and integrations.

Compatible with:

  • Zapier

  • Make.com (Integromat)

  • Integrately

  • Direct API access (CURL, Postman)

Endpoint

POST https://my.simplespa.com/api/clients.php

Authentication

You must include a valid Authorization header using your SimpleSpa API Key:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Replace YOUR_API_KEY with your SimpleSpa Enterprise API Key.

Request Method

  • POST with JSON body

  • or GET with URL parameters (Zapier/Make.com friendly)

Request Parameters

Parameter

Type

Description

page

integer

Page number (default 1)

per_page

integer

Results per page (max 1000)

search

string

Search by first name, last name, email, or mobile

created_before

date (YYYY-MM-DD)

Clients created before this date

created_after

date (YYYY-MM-DD)

Clients created after this date

first_visit_before

date (YYYY-MM-DD)

First visit before this date

first_visit_after

date (YYYY-MM-DD)

First visit after this date

last_visit_before

date (YYYY-MM-DD)

Last visit before this date

last_visit_after

date (YYYY-MM-DD)

Last visit after this date

min_completed_visits

integer

Clients with at least X visits

max_completed_visits

integer

Clients with no more than X visits

birthday_month

integer (1-12)

Clients with a birthday in this month

birthday_day

integer (1-31)

Clients born on this day of month

min_points

integer

Minimum points to search


Example CURL Request

curl -X POST https://my.simplespa.com/api/clients.php \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "page": 1,
  "per_page": 100,
  "created_before": "2022-01-01",
  "completed_visits_min": 5
}'

Example GET Request (Zapier/Make.com Friendly)

https://my.simplespa.com/api/clients.php?page=1&per_page=100&created_before=2022-01-01&completed_visits_min=5

Response Format

The API responds with a JSON object containing the results and pagination information.

Example Response

{
  "success": true,
  "clients": [
    {
      "client_id": "1",
      "firstname": "John",
      "lastname": "Doe",
      "email": "john@example.com",
      "mobile": "1234567890",
      "created": "2021-05-15",
      "first_visit": "2021-06-01",
      "last_visit": "2022-12-15",
      "next_visit": "2023-01-10",
      "completed_visits": 12,
      "points": 100
    },
    ...
  ],
  "page": 1,
  "per_page": 100,
  "total_results": 350
}

Example: Birthday Search

Get all clients born in July:

curl -X GET "https://my.simplespa.com/api/clients.php?birthday_month=7" \
-H "Authorization: Bearer YOUR_API_KEY"

Get all clients born on July 15:

curl -X GET "https://my.simplespa.com/api/clients.php?birthday_month=7&birthday_day=15" \
-H "Authorization: Bearer YOUR_API_KEY"

Response Format

{
  "success": true,
  "clients": [
    {
      "client_id": "e4bc12f93b...",
      "firstname": "John",
      "lastname": "Doe",
      "email": "john@example.com",
      "mobile": "1234567890",
      "dob_year": "1990",
      "dob_month": "7",
      "dob_day": "15",
      "created": "2020-01-15 10:00:00",
      "first_visit": "2020-02-01 09:00:00",
      "last_visit": "2024-04-28 13:30:00",
      "completed_visits": 18,
      "points": 100
    }
  ],
  "page": 1,
  "per_page": 50,
  "total_results": 1
}

Other Examples

We Miss You Campaign

  • Haven’t visited since April 30, 2024

  • And don’t have a future appointment

  • Returns the first 100 results (use page: 2 to paginate)

POST

curl -X POST https://my.simplespa.com/api/clients.php \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "last_visit_before": "2024-04-30",
  "no_future_visits": true,
  "page": 1,
  "per_page": 100
}'

GET

https://my.simplespa.com/api/clients.php?last_visit_before=2025-04-30&no_future_visits=true&page=1&per_page=100

Response Fields

Field

Description

client_id

Unique ID

firstname

Client’s first name

lastname

Client’s last name

email

Client’s email address

mobile

Client’s mobile number

dob_year

Client's birthday year

dob_month

Client's birthday month

dob_day

Client's birthday day

created

When client record was created

first_visit

First appointment date

last_visit

Last appointment date

next_visit

Next booked appointment

completed_visits

Number of completed appointments

points

Loyalty Points accumulated

Ideas for Marketing or Automation

  • Build Birthday Campaigns (clients with upcoming birthdays)

  • Send Loyalty Rewards (clients with completed_visits >= 10)

  • Remind inactive clients (e.g., "last_visit_before": "2023-01-01")

  • Create birthday campaigns (extend API with birthday field if needed)

  • Target VIP clients who spend more frequently

  • Target Clients with the most accumulated loyalty points

  • Export segmented client lists to Mailchimp or any email platform

  • Trigger SMS via Twilio for last-minute promos

Notes

  • Important: for polling-based setup, all new records will be fetched together, which could lead to duplication unless filtered appropriately, please keep a record of those that have been contacted if you are using this for notifications

  • dob_year, dob_month, and dob_day are separate fields.

  • Search Behavior: The search field performs a partial match across first name, last name, email, and mobile phone.

  • Dates must be in YYYY-MM-DD format.

  • Pagination: Default per_page is 100 if not specified. Maximum allowed is 1000 per page.

  • Rate Limiting: Please ensure reasonable usage to avoid throttling. It is recommended to poll no faster than once per minute.

⚠️ IMPORTANT: Never expose your private API key in client-side JavaScript. Always use secure, server-side code to handle sensitive credentials.

PreviousAppointment EndpointNextService Endpoint

Last updated 25 days ago

Page cover image