Customers Overview

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

What Are Customers?

Customers represent the people who book appointments through your OnSched system. Each customer record stores:

• Contact information (name, email, phone)
• Appointment history
• Notification preferences
• Custom fields for additional data
• Optional location association

Customer records enable:

• Faster repeat bookings (no re-entering info)
• Appointment history tracking
• Personalized communications
• Customer relationship management

Core Properties

Required Fields

• firstName (string) – Customer's first name
• lastName (string) – Customer's last name
• email (string) – Email address (unique per company)

Email serves as the unique identifier—you cannot have two customers with the same email in one company.

Optional Fields

• phone (string) – Phone number for SMS notifications or calls
• verificationDate (date) – When customer verified their email/phone
• registrationDate (date) – When customer signed up
• disabled (boolean) – Whether customer account is active
• notificationType (enum) – Preferred notification method (EMAIL, SMS, ALL, NONE)
• latitude / longitude (decimal) – Customer location coordinates
• LocationId (UUID) – Associate customer with specific location (optional)

Audit Fields

• createdBy (string) – Who created the record
• updatedBy (string) – Who last modified the record
• verifiedBy (string) – Who verified the customer

Useful for tracking data provenance.

Custom Fields

• CustomFields (object) – Key-value pairs for extended data

See Customer Custom Fields for details.

Creating Customers

Standalone Customer Creation

Create a customer before booking:

curl -X POST https://v3.onsched.com/v3/customer \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jamie",
    "lastName": "Rodriguez",
    "email": "[email protected]",
    "phone": "+15550123",
    "notificationType": "ALL"
  }'

Response:

{
  "id": "customer-uuid",
  "firstName": "Jamie",
  "lastName": "Rodriguez",
  "email": "[email protected]",
  "phone": "+15550123",
  "notificationType": "ALL",
  "disabled": false,
  "createdAt": "2025-11-25T10:00:00Z"
}

Inline Customer Creation During Booking

Create customer while booking appointment:

curl -X POST "https://v3.onsched.com/v3/appointment?\
LocationId=LOCATION_ID&\
ServiceId=SERVICE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Customer": {
      "firstName": "Taylor",
      "lastName": "Morgan",
      "email": "[email protected]",
      "phone": "+15550456"
    },
    "Unavailability": {
      "startTime": "2025-12-01T14:00:00Z",
      "endTime": "2025-12-01T14:30:00Z"
    },
    "duration": 30
  }'

If a customer with that email exists, OnSched links to the existing record. Otherwise, a new customer is created.

Using Existing Customer

Reference existing customer by ID:

curl -X POST "https://v3.onsched.com/v3/appointment?..." \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Customer": {
      "id": "existing-customer-uuid"
    },
    "Unavailability": {...},
    "duration": 30
  }'

This links the appointment to the existing customer without creating a duplicate.

Retrieving Customers

List All Customers

curl "https://v3.onsched.com/v3/customers?limit=50&page=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response includes pagination:

{
  "data": [
    {
      "id": "customer-1",
      "firstName": "Jamie",
      "lastName": "Rodriguez",
      "email": "[email protected]"
    },
    {
      "id": "customer-2",
      "firstName": "Taylor",
      "lastName": "Morgan",
      "email": "[email protected]"
    }
  ],
  "count": 2,
  "limit": 50,
  "page": 1
}

Get Single Customer

curl https://v3.onsched.com/v3/customer/CUSTOMER_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Includes full details and CustomFields.

Search by Email

curl "https://v3.onsched.com/v3/[email protected]" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Returns matching customer (if exists).

Updating Customers

Use PUT /v3/customer/:id:

curl -X PUT https://v3.onsched.com/v3/customer/CUSTOMER_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+15550789",
    "notificationType": "SMS",
    "CustomFields": {
      "preferredTime": "mornings",
      "newsletter": "true"
    }
  }'

Only include fields you want to change.

Deleting Customers

Customers use soft-delete:

curl -X DELETE https://v3.onsched.com/v3/customer/CUSTOMER_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Deleted customers:

• No longer appear in lists
• Historical appointments remain linked
• Can be restored if needed

Best practice: Disable instead of deleting (disabled: true) to preserve records.

Location Association

Company-Wide Customers

By default, customers are company-scoped:

• Visible to all locations
• Can book at any location
• Shared customer database

Location-Specific Customers

Optionally associate customers with specific locations:

{
  "firstName": "Jordan",
  "lastName": "Lee",
  "email": "[email protected]",
  "LocationId": "location-uuid"
}

When associated:

• Customer primarily books at that location
• Other locations may or may not see them (depends on configuration)

Useful for:

• Franchises with isolated customer bases
• Privacy requirements
• Multi-brand operations under one company

Notification Preferences

Setting Preferences

{
  "notificationType": "EMAIL"  // or "SMS", "ALL", "NONE"
}

• EMAIL – Send notifications via email
• SMS – Send notifications via SMS
• ALL – Both email and SMS
• NONE – No notifications

See Customer SMS for SMS configuration.

Cascading Notifications

If customer has no preference set:

• Defaults to location's customerNotificationType
• Which defaults to company's notificationType

Customer preference overrides location/company settings.

Custom Fields

Extend customers with additional data:

{
  "firstName": "Alex",
  "lastName": "Kim",
  "email": "[email protected]",
  "CustomFields": {
    "membershipTier": "gold",
    "birthday": "1990-05-15",
    "referralSource": "instagram",
    "loyaltyPoints": "1250",
    "preferredStylist": "Jamie"
  }
}

Use CustomFields for:

• Membership information
• Marketing data (referral sources, campaigns)
• Preferences and notes
• Integration identifiers

See Customer Custom Fields for detailed usage.

Appointment History

Retrieve customer's appointments:

curl "https://v3.onsched.com/v3/appointments?CustomerId=CUSTOMER_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Or filter by date range:

curl "https://v3.onsched.com/v3/appointments/filter?\
CustomerId=CUSTOMER_ID&\
startDate=2025-01-01&\
endDate=2025-12-31" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Use appointment history to:

• Track visit frequency
• Identify loyal customers
• Personalize service recommendations
• Calculate lifetime value

Use Cases

Repeat Customers

For returning customers:

1. Search by email during checkout
2. If found, use existing customer ID
3. If not found, create new customer
4. Link to appointment

No duplicate records—fast booking.

Guest Checkout

For one-time bookings:

• Create customer inline during appointment creation
• Customer receives confirmation email
• Record exists for potential future bookings

Membership Programs

Store membership data in CustomFields:

{
  "CustomFields": {
    "membershipId": "MEM-12345",
    "membershipLevel": "premium",
    "memberSince": "2024-01-15",
    "renewalDate": "2025-01-15"
  }
}

Query and filter members for targeted campaigns.

CRM Integration

Sync customers with external CRM:

{
  "CustomFields": {
    "salesforceContactId": "003xx000004TmiD",
    "hubspotId": "12345",
    "lastSyncedAt": "2025-11-25T10:00:00Z"
  }
}

Maintain bidirectional sync between OnSched and CRM.

Best Practices

Use Email as Unique Identifier

• Email is unique per company
• Check for existing customer by email before creating
• Update phone/name as needed, but email remains key

Capture Phone Numbers

Even if not required:

• Enables SMS notifications
• Backup contact method
• Improves no-show reduction

Set Notification Preferences Early

Ask customers during first booking:

• Email, SMS, or both?
• Store preference to respect communication choices

Keep Custom Fields Organized

Document CustomFields schema:

Field Name        | Type    | Purpose
------------------|---------|------------------------
membershipTier    | string  | gold, silver, bronze
birthday          | string  | YYYY-MM-DD format
loyaltyPoints     | string  | numeric string

Consistency makes reporting easier.

Respect Disabled Status

If disabled: true:

• Don't allow new bookings
• Consider why they were disabled (payment issues, abuse, request)
• Re-enable only when appropriate

Audit Customer Data

Periodically:

• Remove duplicate entries (same person, different emails)
• Validate contact information
• Clean up test customers
• Update custom fields

Troubleshooting

Can't create customer—email exists

Cause: Customer with that email already exists.

Solution:

1. Retrieve existing customer by email
2. Use existing customer ID for appointment
3. Or update existing customer record

Notifications not sending to customer

Check:

1. Customer has valid email/phone
2. Customer's notificationType isn't NONE
3. Location has notifications enabled
4. Appointment creation didn't specify skip_notifications: true

See Customer SMS for SMS-specific issues.

Customer appearing at wrong location

If customers are location-scoped:

• Verify LocationId on customer record
• Check if other locations can access location-scoped customers
• Use company-wide customers for multi-location access

Duplicate customers

If same person has multiple records:

• Caused by different emails or manual creation
• Merge manually (update appointments to correct customer, delete duplicate)
• Prevent by searching before creating

Common Questions

Can customers create their own accounts?

Depends on your implementation:

• OnSched doesn't provide customer-facing signup UI
• Build customer portal using API
• Or create customers on-the-fly during booking

Can one customer have multiple emails?

No. Email is unique per customer in a company. If customer changes email:

curl -X PUT https://v3.onsched.com/v3/customer/CUSTOMER_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

Can customers book at multiple locations?

Yes, if customers are company-scoped (not associated with specific location). They can book appointments at any location under the company.

How do I export customer list?

curl "https://v3.onsched.com/v3/customers?limit=1000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" > customers.json

Process exported JSON in your CRM or analytics tool.

Can I import customers from another system?

Yes, use POST /v3/customer for each customer. Consider:

• Bulk import script
• Rate limiting (don't overwhelm API)
• Data validation before import
• Mapping old IDs to new UUIDs

Related Documentation

• Customer Custom Fields – Extending customer data
• Customer SMS – SMS notification configuration
• Appointments – Booking with customers
• Notifications – Notification system overview

Customers are the foundation of your booking system. Maintain accurate records, respect preferences, and use custom fields to tailor OnSched to your customer relationship needs.