Locations

Role in the hierarchy

Locations sit under a company and anchor timezone, operating hours, and which services and resources apply. For the full model, see Architecture: company vs location.

Core API surface

Authenticated company API (Bearer + company context). Exact query parameters and bodies are in the API reference.

Area	Base paths	Notes
Collection	`GET /v3/locations`, `POST /v3/location`	List and create (plus `POST /v3/location/bulk` where supported)
Single record	`GET/PUT/DELETE /v3/location/:id`	Read, update, soft-delete patterns per your account rules
Weekly hours	`GET/POST /v3/location/:id/weeklyAvailability`	Schedule-mode baseline for the location
Associations	`POST .../setAssociations`, `PUT .../addAssociations`, `PUT .../removeAssociations`	Link related entities as your integration requires

Set each location’s IANA timezone so GET /v3/availability and appointments interpret local dates correctly.

Custom fields

Each location carries a free-form CustomFields object of string key/value pairs, set on POST /v3/location and PUT /v3/location/:id. Use it for identifiers your own systems need — a region code, a store number, a CRM record id.

GET /v3/locations filters on those values using dot notation:

curl "https://v3.onsched.com/v3/locations?CustomFields.regionCode=east-1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Use CustomFields.<key>=<value> query parameters.
Values are matched exactly and case-sensitively.
Multiple CustomFields.* parameters are combined with AND.
Empty string values are allowed.
Other CustomFields query shapes (for example CustomFields={...} or customFields.<key>) are rejected with 400.
Combine them with the existing name, services, resources, and include filters.

The filter requires an authenticated company request. GET /v3/public/locations rejects CustomFields.<key> with 400, since public location responses return only id and name.

Settings and limits

Company- and entity-level booking rules often reference location context. See Settings overview and Booking limits.

Holidays (v3 API)

Company-scoped holiday sets are available on the holidays routes (see Platform API utilities for a short overview). Legacy v1-style per-location holiday CRUD is described in the v1 alias endpoints guide if you still use that shim.

Public and unauthenticated flows

Customer-facing listing of locations for a public client uses GET /v3/public/locations (with API key + public client id). See Authentication.