SmartShifts External API
REST API • Version 1 • Base URL: /api/external/v1
Overview

v1

/api/external/v1

HMAC-SHA256 request signing

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:

HeaderDescriptionRequired
X-API-KeyYour API key (starts with sk_live_)Yes
X-TimestampCurrent Unix timestamp in seconds — must be within 5 minutes of server timeYes
X-SignatureHMAC-SHA256 hex digest of: timestamp + METHOD + path + bodyYes
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.

ScopeAccess
employees:readList and fetch employees
employees:writeCreate and update employees
locations:readList locations
shifts:readList and fetch shifts
shifts:writeCreate, update, and delete shifts
departments:readList departments
time_off:readList time-off requests
time_off:writeCreate time-off requests
time_entries:readList clock-in/out records
hiring:readList job postings and applicants
hiring:writeCreate and update job postings and applicants
onboarding:readList new-hire onboarding records
onboarding:writeInitiate and update onboarding records
tips:readList tips, tip pools, and distributions
tips:writeRecord 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" }
GET /employees employees:read
GET /employees/:id employees:read
POST /employees employees:write
PATCH /employees/:id employees:write
Employee Object Schema
FieldTypeNotes
idstring (uuid)Read-only — unique employee ID
restaurantIdstring (uuid)Read-only — owning restaurant
userIdstring (uuid)Read-only — linked platform user
phonestring | null
rolestringemployee | location_admin | regional_manager | super_admin
positionstring | nullJob title
departmentstring | null
locationIdstring (uuid) | nullPrimary location
hourlyWagenumber | nullIn dollars
employmentTypestringfull_time | part_time | contract | temporary
statusstringpending | active | inactive
hireDatestring | nullYYYY-MM-DD
createdAtstringRead-only — ISO 8601
updatedAtstringRead-only — ISO 8601
Locations
GET /locations locations:read
Shifts
GET /shifts shifts:read
POST /shifts shifts:write
PATCH /shifts/:id shifts:write
DELETE /shifts/:id shifts:write
Departments
GET /departments departments:read
Time Off
GET /time-off time_off:read
POST /time-off time_off:write
Time Entries
GET /time-entries time_entries:read
Hiring

Manage job postings and applicants. Required scope: hiring:read / hiring:write.

GET /jobs hiring:read
GET /jobs/:id hiring:read
POST /jobs hiring:write
PATCH /jobs/:id hiring:write
GET /applicants hiring:read
GET /applicants/:id hiring:read
POST /applicants hiring:write
PATCH /applicants/:id hiring:write
Onboarding

Track new-hire onboarding progress. Required scope: onboarding:read / onboarding:write.

GET /onboarding onboarding:read
GET /onboarding/:id onboarding:read
POST /onboarding onboarding:write
PATCH /onboarding/:id onboarding:write
Tips

Read tip records, pools, and distributions. Required scope: tips:read / tips:write.

GET /tips tips:read
POST /tips tips:write
GET /tip-pools tips:read
GET /tip-distributions tips:read
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.

HeaderValue
X-SmartShifts-Signaturesha256=<hex digest>
X-SmartShifts-EventEvent type string (e.g. employee.created)
X-SmartShifts-TimestampISO 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
EventSchemaWhen it fires
location.createdLocationSite created through the shared location service, including web, mobile and AI/MCP site creation
employee.createdEmployeeNew employee created via API
employee.updatedEmployeeEmployee updated via API
shift.createdShiftNew shift created via API
shift.updatedShiftShift updated via API
shift.deletedShiftShift deleted via API (full snapshot before deletion)
time_off.createdTimeOffRequestTime-off request created via API
pingobjectTest 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
60
requests / minute
1,000
requests / hour

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.

StatusMeaningCommon causes
400Bad RequestMissing required field, invalid date format, resource references wrong organization
401UnauthorizedMissing X-API-Key, invalid signature, timestamp outside 5-minute window
403ForbiddenAPI key lacks the required permission scope
404Not FoundResource ID does not exist in this organization
409ConflictEmployee record already exists for this user in this organization
429Too Many RequestsRate limit exceeded — check Retry-After header
500Internal Server ErrorUnexpected server error
{
  "error":   "unauthorized",
  "message": "Missing X-API-Key header"
}