Notification Guide

Environment tip: All examples use v3.onsched.com for production. Replace the host with api-stage.onsched.com when calling the staging environment.

When to Use

• Keep customers, resources, and company admins informed about booking changes.
• Trigger reminder messages before appointments start.
• Customize notification channels per recipient without handling transport yourself.

Notification Model

• Supported types: NEW_APPOINTMENT, APPOINTMENT_CONFIRMED, APPOINTMENT_CANCELLED, APPOINTMENT_RESCHEDULED, APPOINTMENT_REMINDER.
• Channels: EMAIL, SMS, ALL, or NONE per recipient (company, location/customer, each resource).
• Templates: Built from OnSched email layouts with merge variables. Custom templates live in the dashboard; API requests just choose whether to send them.

Email template merge syntax

Customer, company, and resource notifications use the same merge engine as GET / POST /v3/emailTemplates. Supported placeholders use double curly braces: {{path.to.field}}. You can chain filters with a pipe: {{appointment.time | date:'%B %d, %Y':'en-US'}} (see existing dashboard examples).

Single resource (backward compatible) — {{resource.name}}, {{resource.email}}, {{appointment.resource}}, and {{customer.resource}} still refer to the first resource on the appointment. Existing templates keep working when an appointment has multiple resources (e.g. couples or multi-provider bookings).

All resources on the appointment

• {{appointment.resources}} — Comma-separated list of every resource name on the booking (same order as stored on the appointment).

• {{#each path}}...{{/each}} — Repeat a fragment for each element of an array at path. Most common: list every provider by name or email, one line per resource:

  Text

  Providers:
  {{#each resources}}- {{name}} ({{email}})
  {{/each}}

  Inside the block, bare keys such as {{name}} or {{email}} refer to the current resource row; paths such as {{appointment.time}} or {{customer.firstName}} still refer to the outer appointment/customer. Nested {{#each}} blocks are not supported. If the list is empty or the path is missing, the block renders nothing.

• {{resources.0.name}}, {{resources.1.name}}, … — Optional indexed access when you need a fixed number of slots in the copy.

Automatic Sending

autoSendAllNotifications is invoked whenever appointments are created, booked, rescheduled, confirmed, or cancelled—as long as the request body does not include skip_notifications=true. It:

1. Builds subject/text/html per notification type.
2. Determines who should receive the message based on company.notificationType, location.customerNotificationType, and resource.notificationType.
3. Sends email via sendEmail and SMS via sendSMS for each recipient that has a reachable channel.

Configuration Checklist

• Company-level defaults: Set contact email/phone and default notification type in the dashboard.
• Location overrides: Configure customerNotificationType and reminder lead time (remindBefore minutes). During appointment creation the API converts this into remindAt.
• Resource preferences: Resources can opt into or out of notifications individually.
• Custom templates: Use the email template endpoints to update branding. Notifications will call buildCustomNotificationContent automatically.

Example: Skipping Platform Notifications

curl -X POST https://v3.onsched.com/v3/appointment \
  -H "Authorization: Bearer <token>" \
  -H "x-api-key: <company-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "LocationId": "<location>",
    "ServiceId": "<service>",
    "skip_notifications": true,
    "Customer": { "firstName": "Kai", "email": "[email protected]" },
    "Unavailability": {
      "startTime": "2025-04-01T13:00:00Z",
      "endTime": "2025-04-01T13:30:00Z"
    }
  }'

Use this flag only when you send equivalent messages yourself. Otherwise customers and resources will not know about the booking.

Reminder Strategy

• Reminders rely on each location’s remindBefore setting (minutes before start). The API stores remindAt when the appointment is created.
• Use notificationTypes.APPOINTMENT_REMINDER to control reminder templates. Make sure resources have valid phone numbers/emails if they should receive reminder copies.

Troubleshooting

• No notification received: Confirm the recipient’s notification type includes the channel (EMAIL or SMS) and that their contact info is set.
• Duplicate messages: Avoid re-calling the same transition endpoint (e.g., PUT /cancel) unless the state truly changed.
• Custom template placeholders unresolved: Update templates through the dashboard so they match the available variables (appointment, location, service, resource, customer). For appointments with several providers, use {{#each resources}} or {{appointment.resources}} instead of relying only on {{resource.name}} (first resource only).

By delegating delivery to OnSched, you keep users informed while the API enforces the correct triggers and timing.