SmartShifts External API
REST API • Version 1 • Base URL: /api/external/v1
Overview
Authentication HMAC-SHA256 request signing
Format JSON (application/json)
Authentication
OAuth for customer integrations: Register your application once in Platform Admin → Integration Apps. Each customer connects their organization with consent, without creating their own developer keys. Send Authorization: Bearer ACCESS_TOKEN instead of HMAC headers. See the customer integration OAuth guide for authorization, refresh, permissions and revocation.
Existing API-key integrations: Requests using an API key must be signed using HMAC-SHA256. Include these three headers:
Header Description Required
X-API-Key Your API key (starts with sk_live_) Yes
X-Timestamp Current Unix timestamp in seconds — must be within 5 minutes of server time Yes
X-Signature HMAC-SHA256 hex digest of: timestamp + METHOD + path + body Yes
Signing Example (Node.js)
const crypto = require('crypto');
const apiKey = 'sk_live_...';
const apiSecret = 'your-api-secret';
const method = 'GET';
const path = '/api/external/v1/employees';
const body = ''; // empty for GET
const timestamp = Math.floor(Date.now() / 1000).toString();
const message = timestamp + method + path + body;
const signature = crypto.createHmac('sha256', apiSecret)
.update(message)
.digest('hex');
// Then pass these as request headers:
// X-API-Key: apiKey
// X-Timestamp: timestamp
// X-Signature: signature
Permissions
API keys are granted one or more permission scopes. Each endpoint requires a specific scope.
Scope Access
employees:read List and fetch employees
employees:write Create and update employees
locations:read List locations
shifts:read List and fetch shifts
shifts:write Create, update, and delete shifts
departments:read List departments
time_off:read List time-off requests
time_off:write Create time-off requests
time_entries:read List clock-in/out records
hiring:read List job postings and applicants
hiring:write Create and update job postings and applicants
onboarding:read List new-hire onboarding records
onboarding:write Initiate and update onboarding records
tips:read List tips, tip pools, and distributions
tips:write Record tips
Employees
Employee records are linked to existing platform user accounts. Use the SmartShifts admin UI to create and invite users; this API manages their employee data.
Job titles and access roles are different. Employee list, detail and API write responses include jobTitle (first title or null), jobTitles (all assigned titles), position (legacy title), positionIds, resolvedTitles and jobTitleStatus. The role field controls app permissions; values such as employee or super_admin do not describe job duties. Status is available, missing (no titles), or incomplete (some assigned position IDs cannot be resolved). Titles do not establish food handling, alcohol service, food-safety responsibility or legal training requirements. When job information is missing or incomplete, disclose uncertainty and request duties or an explicit organization training policy before presenting a training plan as ready. API employee.created and employee.updated webhook data also include these title fields.
{ "role": "employee", "position": null, "positionIds": ["position-server"], "resolvedTitles": ["Server"], "jobTitle": "Server", "jobTitles": ["Server"], "jobTitleStatus": "available" }
List all employees for your organization.
Query Parameters
Parameter Type Required Description
locationId string No Filter by location UUID
status string No pending | active | inactive
limit integer No Max results (default: 100, max: 500)
offset integer No Pagination offset (default: 0)
Response
{ "data": Employee[], "meta": { "total": number, "limit": number, "offset": number } }
Fetch a single employee by UUID.
Response
{ "data": Employee }
Create an employee record for an existing platform user. Returns 201 Created .
Request Body
Field Type Required Description
userId string (uuid) Yes ID of an existing platform user
phone string No Phone number (max 50 chars)
role string No employee | location_admin | regional_manager | super_admin — default: employee
position string No Job title (max 100 chars)
department string No Department name (max 100 chars)
locationId string (uuid) No Primary location (must belong to this restaurant)
hourlyWage number No Hourly pay rate in dollars (non-negative)
employmentType string No full_time | part_time | contract | temporary — default: full_time
status string No pending | active | inactive — default: active
hireDate string No Date hired in YYYY-MM-DD format
Response
{ "data": Employee } — HTTP 201
Partially update an employee. Only fields you include are changed. The userId field cannot be changed.
Request Body
All fields are optional. Include only the fields you want to update.
Field Type Description
phone string Phone number (max 50 chars)
role string employee | location_admin | regional_manager | super_admin
position string Job title (max 100 chars)
department string Department name (max 100 chars)
locationId string (uuid) Primary location ID
hourlyWage number Hourly pay rate in dollars
employmentType string full_time | part_time | contract | temporary
status string pending | active | inactive
hireDate string Date in YYYY-MM-DD format
Response
{ "data": Employee }
Employee Object Schema
Field Type Notes
id string (uuid) Read-only — unique employee ID
restaurantId string (uuid) Read-only — owning restaurant
userId string (uuid) Read-only — linked platform user
phone string | null
role string employee | location_admin | regional_manager | super_admin
position string | null Job title
department string | null
locationId string (uuid) | null Primary location
hourlyWage number | null In dollars
employmentType string full_time | part_time | contract | temporary
status string pending | active | inactive
hireDate string | null YYYY-MM-DD
createdAt string Read-only — ISO 8601
updatedAt string Read-only — ISO 8601
Locations
List all locations for your organization.
Query Parameters
Parameter Type Required Description
limit integer No Max results (default: 50, max: 200)
offset integer No Pagination offset (default: 0)
Response
{ "data": Location[], "total": number }
Shifts
List shifts within an optional date range.
Query Parameters
Parameter Type Required Description
locationId string No Filter by location UUID
employeeId string No Filter by employee UUID
startDate string (ISO 8601) No Range start
endDate string (ISO 8601) No Range end
limit integer No Max results (default: 50, max: 200)
offset integer No Pagination offset (default: 0)
Response
{ "data": Shift[], "total": number }
Create a new shift. Returns 201 Created .
Request Body
Field Type Required Description
startTime string (ISO 8601) Yes Shift start time
endTime string (ISO 8601) Yes Shift end time
employeeId string (uuid) No Assigned employee
locationId string (uuid) No Location for this shift
position string No Position/role label (max 100 chars)
notes string No Shift notes
shiftStatus string No scheduled | completed | late | early_departure | late_and_early | missed | in_progress — default: scheduled
payRate number No Override pay rate for this shift (non-negative)
Response
{ "data": Shift } — HTTP 201
Partially update a shift. Only fields you include are changed.
Request Body (all optional)
Field Type Description
startTime string (ISO 8601) Shift start time
endTime string (ISO 8601) Shift end time
employeeId string (uuid) | null Assigned employee (null to unassign)
locationId string (uuid) | null Shift location
position string | null Position label
notes string | null Shift notes
shiftStatus string scheduled | completed | late | early_departure | late_and_early | missed | in_progress
payRate number | null Override pay rate
Response
{ "data": Shift }
Delete a shift. Returns 204 No Content on success.
Departments
List all departments for your organization.
Query Parameters
Parameter Type Required Description
limit integer No Max results (default: 50, max: 200)
offset integer No Pagination offset (default: 0)
Response
{ "data": Department[], "total": number }
Time Off
List time-off requests for your organization.
Query Parameters
Parameter Type Required Description
employeeId string No Filter by employee UUID
status string No pending | approved | denied
startDate string (YYYY-MM-DD) No Filter requests starting on or after this date
endDate string (YYYY-MM-DD) No Filter requests starting on or before this date
limit integer No Max results (default: 50, max: 200)
offset integer No Pagination offset (default: 0)
Response
{ "data": TimeOffRequest[], "total": number }
Create a time-off request. Returns 201 Created .
Request Body
Field Type Required Description
employeeId string (uuid) Yes Employee requesting time off (must belong to this restaurant)
startDate string (YYYY-MM-DD) Yes First day of time off
endDate string (YYYY-MM-DD) Yes Last day of time off
reason string No Reason for the request
type string No vacation | sick | personal | bereavement | unpaid | other — default: personal
Response
{ "data": TimeOffRequest } — HTTP 201
Time Entries
List clock-in/out records for your organization.
Query Parameters
Parameter Type Required Description
employeeId string No Filter by employee UUID
locationId string No Filter by location UUID
startDate string (ISO 8601) No Range start
endDate string (ISO 8601) No Range end
limit integer No Max results (default: 50, max: 200)
offset integer No Pagination offset (default: 0)
Response
{ "data": TimeEntry[], "total": number }
Hiring
Manage job postings and applicants. Required scope: hiring:read / hiring:write.
List all job postings for your organization.
Query Parameters
Parameter Type Required Description
status string No Filter by status: open, closed, draft
locationId string No Filter by location UUID
limit integer No Max results (default: 50, max: 200)
offset integer No Pagination offset (default: 0)
Response
{ "data": JobPosting[], "total": number }
Get a single job posting by ID.
Response
{ "data": JobPosting }
Create a new job posting. Fires job_posting.created webhook.
Required Body Fields
Field Type Description
title string Job title
description string Full job description
employmentType string full_time, part_time, contractor, temporary, seasonal
flsaStatus string exempt or non_exempt
Response
{ "data": JobPosting } — HTTP 201
Update a job posting (all fields optional). Fires job_posting.updated webhook.
Response
{ "data": JobPosting }
List applicants across all job postings.
Query Parameters
Parameter Type Required Description
jobPostingId string No Filter by job posting UUID
stage string No applied, screening, interview_scheduled, interviewed, offer_extended, hired, rejected
limit integer No Max results (default: 50, max: 200)
offset integer No Pagination offset (default: 0)
Response
{ "data": Applicant[], "total": number }
Get a single applicant by ID.
Response
{ "data": Applicant }
Submit a new applicant. Fires applicant.created webhook.
Required Body Fields
Field Type Description
firstName string First name
lastName string Last name
email string Email address
Response
{ "data": Applicant } — HTTP 201
Update an applicant's details or advance their stage. Fires applicant.updated webhook.
Common Use: Advance Stage
{ "currentStage": "interview_scheduled" }
Response
{ "data": Applicant }
Onboarding
Track new-hire onboarding progress. Required scope: onboarding:read / onboarding:write.
List new-hire onboarding records.
Query Parameters
Parameter Type Required Description
status string No pending, in_progress, completed, expired
employeeId string No Filter by employee UUID (once onboarded)
limit integer No Max results (default: 50, max: 200)
offset integer No Pagination offset (default: 0)
Response
{ "data": NewHireOnboarding[], "total": number }
Get a single onboarding record by ID.
Response
{ "data": NewHireOnboarding }
Initiate onboarding for a new hire. Fires onboarding.created webhook.
Required Body Fields
Field Type Description
firstName string New hire first name
lastName string New hire last name
email string Email address for invite
position string Job position / role
startDate string (ISO 8601) First day of work
initiatedBy string Employee UUID of the manager initiating onboarding
Response
{ "data": NewHireOnboarding } — HTTP 201
Update an onboarding record (e.g. mark completed). Fires onboarding.updated webhook.
Response
{ "data": NewHireOnboarding }
Tips
Read tip records, pools, and distributions. Required scope: tips:read / tips:write.
List individual tip records for your organization.
Query Parameters
Parameter Type Required Description
employeeId string No Filter by employee UUID
locationId string No Filter by location UUID
startDate string (ISO 8601) No Range start
endDate string (ISO 8601) No Range end
limit integer No Max results (default: 50, max: 200)
offset integer No Pagination offset (default: 0)
Response
{ "data": Tip[], "total": number }
Record a tip for an employee. Fires tip.created webhook. Useful for syncing tips from a POS system.
Required Body Fields
Field Type Description
employeeId string Employee UUID receiving the tip
amount string Decimal string, e.g. "12.50"
source string manual_cash, credit_card, pos_system, digital_wallet, pooled_distribution, other
date string (ISO 8601) Date/time the tip was earned
Response
{ "data": Tip } — HTTP 201
List active tip pools.
Query Parameters
Parameter Type Required Description
locationId string No Filter by location UUID
isActive boolean No Filter by active status (true or false)
limit integer No Max results (default: 50, max: 200)
offset integer No Pagination offset (default: 0)
Response
{ "data": TipPool[], "total": number }
List calculated tip distribution records.
Query Parameters
Parameter Type Required Description
poolId string No Filter by tip pool UUID
employeeId string No Filter by employee UUID
startDate string (ISO 8601) No Filter by period start
endDate string (ISO 8601) No Filter by period end
limit integer No Max results (default: 50, max: 200)
offset integer No Pagination offset (default: 0)
Response
{ "data": TipDistribution[], "total": number }
Webhooks
Register HTTPS endpoints to receive signed POST payloads when data changes. Configure webhooks in Settings → Integrations → API & Webhooks.
Signature Verification
Every webhook delivery includes a signature you should verify before processing the payload.
Header Value
X-SmartShifts-Signature sha256=<hex digest>
X-SmartShifts-Event Event type string (e.g. employee.created)
X-SmartShifts-Timestamp ISO 8601 timestamp of the event
Verify in Node.js
const crypto = require('crypto');
function verifyWebhook(rawBody, signingSecret, signatureHeader) {
const expected = 'sha256=' + crypto.createHmac('sha256', signingSecret)
.update(rawBody)
.digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}
Event Types
Event Schema When it fires
location.created Location Site created through the shared location service, including web, mobile and AI/MCP site creation
employee.created Employee New employee created via API
employee.updated Employee Employee updated via API
shift.created Shift New shift created via API
shift.updated Shift Shift updated via API
shift.deleted Shift Shift deleted via API (full snapshot before deletion)
time_off.created TimeOffRequest Time-off request created via API
ping object Test delivery from the Settings UI
Payload Shape
{
"event": "employee.created", // event type string
"restaurantId": "uuid", // restaurant that triggered this
"timestamp": "2025-01-15T14:30:00Z", // ISO 8601
"data": { /* resource object */ } // the created/updated/deleted record
}
New Site Example
Subscribe to location.created (Site Created), or * for all events. Site updates do not emit this creation event. The payload contains the persisted site record; restaurantId identifies its organization.
{
"appName": "SmartShifts",
"event": "location.created",
"restaurantId": "44444444-4444-4444-8444-444444444444",
"timestamp": "2026-11-17T16:00:00.000Z",
"data": {
"id": "33333333-3333-4333-8333-333333333333",
"restaurantId": "44444444-4444-4444-8444-444444444444",
"name": "Downtown Office",
"siteNumber": "1001",
"siteStatus": "active",
"isActive": true,
"timezone": "America/Los_Angeles"
}
}
Example fields are abbreviated. Deliveries include the existing signature headers and use the same retry policy as other events.
Retry Policy
Deliveries are retried up to 4 times if your endpoint does not respond with HTTP 2xx within 10 seconds.
Schedule: immediate → +5s → +30s → +5min
Rate Limits
Limits apply per API key. When exceeded, the API returns HTTP 429 with a Retry-After header indicating how many seconds to wait before retrying.
Error Codes
All errors are returned as JSON with a message field and optionally an error field.
Status Meaning Common causes
400 Bad Request Missing required field, invalid date format, resource references wrong organization
401 Unauthorized Missing X-API-Key, invalid signature, timestamp outside 5-minute window
403 Forbidden API key lacks the required permission scope
404 Not Found Resource ID does not exist in this organization
409 Conflict Employee record already exists for this user in this organization
429 Too Many Requests Rate limit exceeded — check Retry-After header
500 Internal Server Error Unexpected server error
{
"error": "unauthorized",
"message": "Missing X-API-Key header"
}