Timely API
Timely is salon, spa, and beauty business software that handles online booking, calendar scheduling, point of sale and payments, client management, marketing, and reporting. Its API lets you programmatically pull appointments, clients, sales, services, and staff records—and push updates like new bookings, client records, and sales back into Timely.
What is Timely?
Timely is salon, spa, and beauty business software built around online booking, calendar scheduling, and payments. Salons, spas, barbers, and beauty professionals use Timely to take online bookings, manage their appointment calendar and staff rosters, accept payments through an integrated point of sale, track client history and preferences, run SMS and email marketing campaigns, and report on appointments and sales.
Core product areas include:
- Online booking and integrated booking widgets for client self-service appointments
- Calendar and appointment scheduling with staff rosters and confirmation emails
- Point of sale and payments to accept payment quickly and securely
- Client management tracking client history and preferences
- Marketing, SMS campaigns, automated reminders, and a loyalty/rewards system
- Staff management, inventory management, and reporting on appointments and sales
Common data entities:
- Appointments, Bookings, Services, Service Categories
- Clients/Customers, Client History, Preferences, Consultation Notes
- Sales, Payments, Invoices, Gift Vouchers, Loyalty Points
- Staff, Rosters, Working Hours, Availability
- Products, Stock/Inventory, Suppliers
- Marketing Campaigns, SMS Messages, Reminders, Reward Vouchers
The Timely Integration Challenge
Salons and spas run their entire front desk on Timely, but turning its booking- and POS-driven workflows into API-driven automation is non-trivial:
- OAuth and developer setup gates: API access requires admin-level configuration of an app and redirect URI under Settings, which many integrators are not set up to manage
- Booking-widget and mobile-first data: Much of the client experience flows through online booking widgets and mobile apps rather than a documented data export
- Per-business configuration: Services, pricing, rosters, and packages are tailored per salon—generic integrations break across accounts
- Token and session handling: OAuth2 access tokens expire and must be refreshed, complicating long-running headless automation
- Endpoint coverage variability: The public API surfaces some entities cleanly while other workflows live only behind the web and mobile UI
- Payments and sales reconciliation: POS transactions, gift vouchers, and loyalty points need careful matching back to appointments and clients
How Supergood Creates Timely APIs
Supergood reverse-engineers authenticated browser flows and Timely's public API to deliver a resilient API layer for your Timely account—across booking, POS, clients, and staff data.
- Handles login, OAuth2 token issuance, and MFA securely in a managed session
- Maintains session continuity with automated token refresh and change detection
- Normalizes responses across appointments, clients, sales, services, and staff so you integrate once and rely on consistent objects
- Aligns with each salon's services, pricing, and roster configuration to ensure accurate, account-specific access
Use Timely with AI agents: Timely MCP Server →
Getting Started
- Schedule Integration Assessment
Book a 30-minute session to confirm your modules, data entities, and authentication model.
- Supergood Generates and Validates Your API
We deliver a production-ready Timely adapter tailored to your account configuration and entitlements.
- Deploy with Monitoring
Go live with continuous monitoring and automatic adjustments as Timely evolves.
API Endpoints
Authentication
/authenticateAuthenticate to a Timely account using login credentials or OAuth2 and obtain a session token for downstream calls.
Scheduling
/appointmentsList appointments and bookings with filters for staff, service, client, status, and date range.
Scheduling
/create_appointmentCreate a new appointment or booking against a service, staff member, and client with the configured pricing.
Clients
/clientsRetrieve client records including history, preferences, and contact details with search and filter parameters.
Sales
/salesPull point-of-sale transactions, payments, invoices, gift vouchers, and loyalty activity across date ranges.
Staff
/staffList staff members, rosters, working hours, and availability used to drive scheduling and reporting.
Use Cases
Sync appointments and client data into your stack
- Pull appointments, bookings, and services into a single warehouse or CRM - Stream new bookings and cancellations to downstream reminder and marketing tools - Reconcile client history and preferences across locations for a unified client view
Automate point-of-sale and payments reporting
- Sync sales, payments, and invoices from Timely POS into accounting and BI systems - Match gift vouchers and loyalty points back to clients and appointments - Surface daily takings and outstanding balances to finance dashboards
Power booking and staff workflows
- Push new bookings created in third-party booking flows into Timely's calendar - Pull staff rosters and availability to drive external scheduling tools - Trigger automated reminders and confirmations when appointments change
Drive marketing and loyalty campaigns
- Export client lists, visit history, and spend for targeted SMS and email campaigns - Sync loyalty points and reward vouchers into a unified rewards program - Trigger rebooking and birthday outreach based on appointment activity
Technical Specifications
Authentication
Login credentials and OAuth2 access/refresh tokens handled in a managed session, with MFA where enabled
Connectivity
Authenticated browser flows plus Timely's public API surfaced where exposed by the account
Response format
Normalized JSON across appointment, client, sale, service, and staff objects
Rate limits
Adaptive throttling tuned to your account to avoid Timely-side limits
Session management
Automatic OAuth2 token refresh, session continuity, and credential rotation
Data freshness
Near real-time pulls for appointments, sales, and clients with optional scheduled batch syncs
Security
Encrypted credential vault, scoped access tokens, SOC 2-aligned controls, and audit logging
Webhooks
Event-style callbacks for new bookings, cancellations, sale completions, and client changes
Latency
Sub-second reads on cached entities; multi-second writes when posting bookings and sales
Throughput
Horizontally scaled workers sized to multi-location salon and spa volume
Reliability
Retry, backoff, and idempotency keys for bookings, payments, and client updates
Adaptation
Continuous monitoring of Timely API and UI changes and per-account configuration drift
Frequently asked questions
Yes. Supergood normalizes appointments, bookings, client records, and point-of-sale transactions into a single API surface, so scheduling, CRM, and payments data integrate once across your Timely account.
No. Supergood manages the OAuth2 flow, including app registration concerns, token issuance, and automatic refresh, so you do not have to maintain developer credentials or redirect URIs yourself.
Yes. Supergood reverse-engineers authenticated browser and app flows in addition to the public API, so entities that live behind the UI are still exposed through the normalized API surface.
Yes. Supergood profiles each location's services, pricing, rosters, and staff so multi-location accounts return consistent, account-specific objects rather than a generic schema.
Sales, payments, gift vouchers, and loyalty activity are normalized and matched back to the originating client and appointment, so finance and rewards data stay reconciled.