V1 Migration & Alias Endpoints

Use this guide if: your application already calls v1-style endpoints such as /consumer/v1/... or /setup/v1/..., and you want to move traffic onto the v3 platform host with the least possible application change.

Production host: https://v3.onsched.com

Staging host: https://api-stage.onsched.com

Overview

OnSched provides a v1 compatibility layer on the v3 platform so existing integrations can continue to call familiar v1 routes while the request is actually fulfilled by v3 services.

In practice, this means your application can keep using paths like:

• /consumer/v1/availability/...
• /consumer/v1/appointments
• /setup/v1/locations
• /setup/v1/services

but send those requests to the v3 host instead of the legacy v1 host.

This is an alias layer, not a separate product. It translates:

• v1 authentication context into the correct company context
• v1 legacy IDs into v3 UUIDs
• v1 request shapes into v3 request payloads and query params
• v3 responses back into v1-style response objects

The goal is to reduce the amount of client code you need to change during migration, while still moving traffic onto the v3 runtime and data model.

What Actually Changes for Clients

If you are using the alias layer, the main change is the host.

Before

https://api.onsched.com/consumer/v1/...
https://api.onsched.com/setup/v1/...

After

https://v3.onsched.com/consumer/v1/...
https://v3.onsched.com/setup/v1/...

For many existing flows, the path and payload can remain the same.

What does not automatically become v3-native:

• Your client is still calling v1-shaped endpoints.
• Your client is still receiving mostly v1-shaped responses.
• Your integration should still be treated as a compatibility integration until you intentionally move to /v3/* endpoints and v3 auth.

How the Alias Layer Works

Every request through /consumer/v1/* or /setup/v1/* follows the same general flow.

1. The request arrives with a v1 bearer token

The shim expects an Authorization: Bearer ... header containing a v1 token. It decodes that token and extracts:

• the v1 client ID
• the v1 company ID
• the token issuer so it can confirm production vs sandbox usage

Important behavior:

• a sandbox v1 token can only be used against api-stage.onsched.com
• a production v1 token can only be used against production
• the token is decoded for routing/context purposes before the request is translated

2. The shim resolves the company

Using the v1 company ID from the token, the shim looks for a matching v3 company. If the company does not exist yet in v3, the first request can create it automatically using data fetched from v1.

That first request may also create company credentials in v3, including:

• a v3 client ID
• a v3 client secret
• a v3 API key

This is part of why the very first request for a company can be slower than later requests.

3. The shim gets a v3 machine token

After the company context is known, the shim requests a v3 OAuth token internally from:

/v3/oauth/token

Your client does not have to call that endpoint as part of the alias flow. The shim does it on the server side.

4. Legacy IDs are resolved

When your request includes IDs such as:

• locationId
• serviceId
• resourceId
• customerId
• appointmentId

the shim tries to resolve them to the correct v3 UUID.

Resolution is flexible:

• if the incoming value is a legacy v1 ID, it looks up or creates a mapping
• if the incoming value is already a v3 UUID, many handlers will accept it directly
• if the entity does not exist yet in v3, the shim may fetch it from v1 and create it lazily

This lets existing client code continue using v1 IDs while the v3 platform works internally with UUIDs.

5. The request is translated to a v3 call

The shim builds the equivalent v3 request, calls the relevant /v3/* endpoint, then maps the result back to a v1-like response shape.

Examples:

• availability requests become GET /v3/availability
• appointment creation becomes POST /v3/appointment or POST /v3/appointment/hold
• service/resource/location reads become GET /v3/service/:id, GET /v3/resource/:id, GET /v3/location/:id
• setup CRUD operations call the corresponding v3 management endpoints

Base URL Migration Strategy

For most existing v1 API clients, the lowest-risk first step is:

1. Keep the same v1 path structure.
2. Keep the same request payloads.
3. Change the host to v3.onsched.com.
4. Test every booking and setup flow your application uses.

This gives you a compatibility bridge before doing a full endpoint rewrite.

Recommended migration sequence

1. Move traffic from api.onsched.com to v3.onsched.com while keeping /consumer/v1/* and /setup/v1/*.
2. Validate core flows end-to-end in production-like data.
3. Identify any unsupported or partially supported endpoints.
4. Migrate high-value flows to native /v3/* endpoints over time.
5. Move auth and credential handling to the native v3 model once you are ready to retire the alias layer.

Supported Route Families

The alias layer covers a meaningful subset of v1 consumer and setup APIs, especially the flows needed for booking, appointments, and core entity management.

Consumer routes

These are mounted under:

https://v3.onsched.com/consumer/v1

Broadly supported route families include:

• availability
• appointments
• locations
• services
• resources
• customers
• service allocations

Representative examples:

• GET /consumer/v1/availability/:serviceId/:startDate/:endDate
• GET /consumer/v1/availability/:serviceId/:startDate/:endDate/days
• POST /consumer/v1/appointments
• PUT /consumer/v1/appointments/:id/book
• PUT /consumer/v1/appointments/:id/reschedule
• GET /consumer/v1/locations
• GET /consumer/v1/services/:id/resources
• GET /consumer/v1/customers

Setup routes

These are mounted under:

https://v3.onsched.com/setup/v1

Broadly supported route families include:

• companies
• domains
• business users
• customers
• locations
• services
• resources
• availability management
• allocations
• recurring resource blocks

Representative examples:

• GET /setup/v1/companies
• PUT /setup/v1/companies
• GET /setup/v1/locations/:id/settings
• POST /setup/v1/services
• PUT /setup/v1/services/:id/availability
• POST /setup/v1/resources/:id/block
• POST /setup/v1/resources/:id/services

Unshimmed routes

Any route under /consumer/v1/* or /setup/v1/* that is not implemented by the shim returns 410 Gone with a deprecation message.

That means you should not assume the entire historical v1 API surface is available just because the host has changed.

Auth Expectations and Important Caveat

This is the most important design detail for client developers.

The alias layer expects a v1 token today

The compatibility endpoints currently expect the client to send a valid v1 bearer token in the Authorization header.

That means a simple host swap is only sufficient if your application can still obtain and send a valid v1 token.

The alias layer does not expose a public v1 token alias

The v3 platform exposes native client credentials at:

POST /v3/oauth/token

but there is no public compatibility alias for the legacy v1 token endpoint on the v3 host.

Practically, this means:

• if your app already has a working way to obtain a v1 token, you can usually keep using it while moving API calls to v3.onsched.com
• if your app expects the host change alone to also replace the old token flow, that is not the current behavior
• the alias layer should be considered an application/API compatibility bridge, not a complete auth-compatibility bridge

What to do if you want full v3-native auth

If you want to fully modernize the integration, plan a second migration step where you move from:

• v1 token acquisition
• v1 alias paths

to:

• v3 OAuth client credentials
• native /v3/* endpoints

ID Behavior

One of the main jobs of the alias layer is to shield client applications from the v1-to-v3 identifier change.

What clients can continue to send

Most supported alias routes accept legacy v1 IDs in the same places your old integration used them:

• path parameters
• query parameters
• request bodies

Examples:

• serviceId
• locationId
• resourceId
• customerId
• appointment IDs in path segments

What the platform uses internally

Internally, v3 uses UUIDs for primary identifiers. The shim resolves or creates mappings between:

• v1 legacy IDs
• v3 UUIDs

What clients usually receive back

Most mapped response objects return legacy IDs in the id field so existing client code does not immediately break.

Some responses also include helpful v3 IDs for debugging or migration visibility, especially in appointment and availability responses.

You should not build new production logic that depends on those extra v3 fields unless you are intentionally transitioning to native v3 behavior.

Lazy Migration and First-Request Effects

The alias layer does not require every company and entity to be pre-migrated before use.

Instead, many objects are created lazily when first referenced:

• company
• location
• service
• resource
• customer
• appointment

What this means operationally

• the first request for a company may create that company in v3
• the first request for a service or resource may import it from v1
• first-hit latency may be higher than steady-state latency
• behavior can differ slightly between a cold company and a company that has already been exercised through the shim

This is normal for the compatibility layer and should be considered during rollout and load testing.

Availability Flow Details

Availability is one of the most important translated flows.

Consumer request pattern

Clients continue to call:

GET /consumer/v1/availability/:serviceId/:startDate/:endDate

The shim then:

• resolves the incoming service ID
• resolves locationId if supplied
• resolves resourceId or resourceIds if supplied
• if no location is supplied, attempts to use the primary v1 location
• maps roundRobin=1 to random round robin behavior
• maps roundRobin=2 to balanced round robin behavior
• forwards timezone and duration override settings into the v3 availability query

Important compatibility note

GET /consumer/v1/availability/:serviceId/:startDate/:endDate/unavailable is not reimplemented natively in v3. It is proxied back to the legacy v1 API.

That means this specific endpoint has an extra dependency on legacy v1 availability behavior. If you rely on /unavailable, test it carefully and treat it as higher risk than the main availability endpoint.

Appointment Flow Details

The booking flow is supported, but it is implemented as translation onto v3 appointment behavior.

Create appointment

POST /consumer/v1/appointments

The shim:

• resolves location, service, and resource IDs
• creates any missing related entities in v3 if needed
• translates the v1 body into the v3 appointment or hold request
• creates a mapping if the incoming v1 payload included a legacy appointment ID

Hold versus book

The compatibility layer preserves the v1-style pattern:

• create a hold
• later convert it to a booking

Internally this maps onto:

• POST /v3/appointment/hold
• PUT /v3/appointment/:id/book

If the client passes completeBooking=BK, the shim books immediately instead of creating a hold.

Follow-up appointment actions

Supported follow-up actions include:

• book
• reserve
• cancel
• reschedule
• no-show
• confirm
• delete

As with the rest of the shim, the request may trigger appointment lookup or creation if the mapping does not already exist.

Setup Flow Details

The setup alias layer covers many management operations, but not all v1 concepts map directly into v3.

Areas with good alignment

These generally map well:

• companies
• locations
• services
• resources
• customers
• business users
• weekly availability
• single allocations
• recurring resource blocks

Areas with weaker alignment

These are the main places where v1 and v3 differ structurally:

• service groups
• regions
• customer custom field schema
• some holiday operations
• some settings objects
• some webhook, payment, and calendar integration fields

The compatibility layer usually handles these by returning:

• an empty list
• a reduced object
• a success message instead of full CRUD semantics
• a 501-style not-supported payload

Known Gaps and Behavioral Differences

Client developers should review these carefully before changing the base URL in production.

1. Token acquisition is still a migration concern

The alias endpoints expect a v1 bearer token, while the v3-native token endpoint is /v3/oauth/token. If your client currently obtains its token from legacy v1 identity infrastructure, that part of the flow is not automatically modernized by changing only the API host.

2. Some routes are intentionally stubbed or reduced

Examples:

• service groups are not supported in v3 and return empty or not-supported responses
• regions return an empty list
• customer custom field schema returns empty because v3 uses dynamic fields rather than the old schema model
• holiday item-level get/update/delete behavior is reduced compared with historical v1 semantics

3. Some fields are placeholders rather than true migrated values

Depending on the endpoint, fields such as these may be empty, null, or defaulted:

• webhook URLs
• payment-related fields
• some calendar integration fields
• some travel/proximity fields
• some older settings fields

If your UI or middleware relies on those values being present, verify the response object field by field.

4. Pagination is translated, not identical

v1-style offset and limit are internally converted to v3 page-based requests in several handlers. Standard paging patterns should work, but unusual offset usage should be validated in testing.

5. Timezone-sensitive fields need real testing

The shim translates between different date/time models. Availability and appointment times should be validated with:

• multiple locations
• non-UTC timezones
• daylight saving transitions
• round robin flows

Do not assume a green-path UTC test covers all real booking behavior.

6. Unimplemented endpoints return 410

If your application calls any historical v1 route that is not included in the shim, the request will return 410 Gone. A route inventory step before cutover is strongly recommended.

What We Recommend You Test Before Switching Hosts

At minimum, validate the exact flows your application actually uses.

Consumer-side checklist

• fetch locations
• fetch services
• fetch service resources
• fetch availability
• create a hold
• book a hold
• cancel, confirm, no-show, and reschedule an appointment if your product uses those actions
• fetch appointments by customer, service, resource, and date range
• create and update customers if your booking flow manages customer records directly

Setup-side checklist

• company read/update
• location CRUD
• service CRUD
• resource CRUD
• service-resource linking
• resource-service linking
• service and resource weekly availability read/write
• business user flows if you expose admin tooling
• holiday and email template flows if you use them

Data and compatibility checklist

• verify all IDs returned to the client are the format your code expects
• verify your parsing logic tolerates null/default fields
• verify pagination still works with your current UI behavior
• verify timezone-dependent displays against known expected local times
• verify that the first request for a not-yet-migrated company succeeds within your timeout expectations

Best Practices for Rollout

Treat the alias layer as a bridge

The alias layer is a practical way to move off the legacy runtime with less client churn, but it should not be mistaken for a permanent one-to-one clone of every v1 behavior.

Keep your first rollout narrow

If possible:

• switch a single application or tenant first
• validate real booking traffic
• monitor first-hit latency and errors
• then expand

Inventory your endpoints before cutover

Make a list of every /consumer/v1/* and /setup/v1/* route your app calls. Compare that list with the supported shim surface and explicitly test any endpoint that depends on legacy-only concepts.

Plan the second migration now

A good long-term target is:

• v3 OAuth credentials
• native /v3/* endpoints
• v3 UUIDs in your own data model

Using the alias layer first is fine, but it works best when it is part of a staged migration plan rather than the end state.

Quick Reference

Lowest-effort migration

• change the host to https://v3.onsched.com
• keep using /consumer/v1/* and /setup/v1/*
• keep using v1 request/response shapes
• continue sending a valid v1 bearer token
• regression test every used endpoint

Highest-confidence long-term migration

• move auth to /v3/oauth/token
• move endpoints to /v3/*
• store v3 UUIDs in your own system
• use the alias layer only as a temporary bridge

Summary

The alias endpoints on v3.onsched.com let existing v1 client applications keep their familiar route structure while the platform performs request translation, ID mapping, lazy entity creation, and response transformation behind the scenes.

For many teams, that makes host migration much faster. The two important things to keep in mind are:

• this layer is compatibility-focused, not full v1 emulation
• changing the host does not by itself convert the authentication model into native v3 auth

If you approach the move as a staged migration, validate the exact endpoints your application uses, and account for the known compatibility gaps, the alias layer can provide a safe path from v1 traffic to the v3 platform.