Service Providers

Service providers are the staff who perform services. A service person is a staff profile; a service provider links a service to a person with optional price and duration overrides; time off records when a provider is unavailable.

SDK coverage

These operations are demonstrated in the TypeScript SDK guide. The Python SDK guide does not include service-person, provider-assignment, or time-off examples.

ServicePerson

Field	Type	Required	Description
id	string	Yes	Unique identifier
locationId	string | null	No	Location assignment. Null = all locations
userAccountId	string | null	No	Linked user account for staff login and calendar sync
name	string	Yes	Display name shown to customers during booking
avatar	string (URL) | null	No	Provider avatar URL
description	string | null	No	Bio shown during booking
skills	string[] | null	No	Skill IDs this provider can perform
commissionPercent	number (0-100) | null	No	Commission percentage for payroll
scheduleId	string | null	No	Link to scheduling system for availability
bookableOnline	boolean	Yes	Customers can book online (default: true)
bookableByStaff	boolean	Yes	Staff can assign internally (default: true)
isActive	boolean	Yes	Whether provider is active (default: true)

Example

{
  "id": "sp_abc123",
  "locationId": "loc_123",
  "userAccountId": "user_jane",
  "name": "Jane Smith",
  "description": "Senior stylist with 10 years experience",
  "skills": ["skill_haircut", "skill_coloring", "skill_styling"],
  "commissionPercent": 45,
  "scheduleId": "sched_jane_2024",
  "bookableOnline": true,
  "bookableByStaff": true,
  "isActive": true
}

ServiceProvider

Links a service to a provider, with optional overrides.

Field	Type	Required	Description
id	string	Yes	Unique identifier
serviceId	string	Yes	Service being assigned
providerId	string	Yes	Provider ID (ServicePerson ID)
priceOverride	number | null	No	Provider-specific price. Null = service default
durationOverride	number | null	No	Provider-specific duration (minutes). Null = service default
active	boolean	Yes	Whether assignment is active (default: true)

ServiceProviderTimeOff

Records periods when a provider is unavailable.

Field	Type	Required	Description
id	string	Yes	Unique identifier
providerId	string	Yes	Provider ID (ServicePerson ID)
type	enum	Yes	recurring or specific
startDate	number	Yes	Start timestamp (Unix epoch seconds)
endDate	number	Yes	End timestamp (Unix epoch seconds)
reason	string | null	No	Reason for time off
status	enum	Yes	approved, pending, or rejected (default: pending)
recurrence	object | null	No	Recurrence rule (required if type = recurring)

Validation: endDate must be >= startDate. If type is recurring, recurrence is required; if specific, recurrence must be empty.

Examples

One-time vacation:

{
  "id": "pto_vacation1",
  "providerId": "sp_abc123",
  "type": "specific",
  "startDate": 1704067200,
  "endDate": 1704672000,
  "reason": "Holiday vacation",
  "status": "approved",
  "recurrence": null
}

Weekly recurring (every Monday off, 0=Sunday … 6=Saturday):

{
  "id": "pto_mondays",
  "providerId": "sp_abc123",
  "type": "recurring",
  "startDate": 1704067200,
  "endDate": 1735689600,
  "reason": "Regular day off",
  "status": "approved",
  "recurrence": { "dayOfWeek": ["1"] }
}

SDK — Service persons

const person = await client.servicePersons.create({
  name: 'Jane Smith',
  description: 'Senior hair stylist with 10 years experience',
  locationId: 'loc_123',
  commissionPercent: 35,
  bookableOnline: true,
  bookableByStaff: true,
  isActive: true,
});

const loaded = await client.servicePersons.get('person_123');

const atLocation = await client.servicePersons.getByLocation('loc_123');

const updated = await client.servicePersons.update({
  id: 'person_123',
  commissionPercent: 45,
  bookableOnline: false,
});

const all = await client.servicePersons.list();

await client.servicePersons.delete('person_123');

SDK — Service providers (assignments)

const serviceProvider = await client.serviceProviders.create({
  serviceId: 'service_123',
  providerId: 'person_123',
  priceOverride: 75.00,
  durationOverride: 45,
  active: true,
});

const byService = await client.serviceProviders.getByService('service_123');
const byProvider = await client.serviceProviders.getByProvider('person_123');

const updated = await client.serviceProviders.update({
  id: 'sp_123',
  priceOverride: 90.00,
  active: false,
});

await client.serviceProviders.delete('sp_123');

tip

Link each ServicePerson to a userAccountId for calendar sync and staff login, and set a scheduleId for accurate availability calculations.