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.

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).

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