SmartQ.tv Developer API Documentation

Start with discovery, then follow modules

Exchange your application credentials from a trusted backend, then discover what the current application can see and request only the module resources you need.

curl --request POST https://api.smartq.tv/oauth/token \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=YOUR_CLIENT_ID" \
  --data-urlencode "client_secret=YOUR_CLIENT_SECRET"

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://api.smartq.tv/v1/GROUP_ID/locations

Authorized customers may use Customer API output in their owned or controlled websites, mobile applications, digital experiences, in-venue systems, and internal business applications, subject to their subscription, scopes, customer agreement, and the Customer API Terms of Use.

Official workspace downloads

SmartQ publishes official Postman collection and environment files for the full Developer API.

Server-to-server client credentials

New applications receive a visible Client ID and one-time Client Secret. Exchange them at POST https://api.smartq.tv/oauth/token using form-encoded grant_type=client_credentials, client_id, and client_secret. The response contains an opaque Bearer token with expires_in: 86400 and no refresh token.

{
  "access_token": "REDACTED",
  "token_type": "Bearer",
  "expires_in": 86400
}

Authorization: Bearer ACCESS_TOKEN

Available scopes

Tokens can be granted one or more resource scopes depending on the integration surface needed by the customer.

Full response examples live on a dedicated page

The detailed scope and endpoint examples are maintained separately from the main documentation homepage so they can show full response shapes without turning this page into a payload dump.

Module resources

The SmartQ Developer API is organized around discovery endpoints and module-aware location resources.

SmartQ follows the POS business-day boundary

Sales and ShiftQ business-date resources do not flip at midnight. They follow the location timezone and the POS business-day rule of 4:01 AM through 4:00 AM.

Every resource declares how fresh it should be

Most responses include a refresh block so downstream developers do not need external documentation to understand cadence.

{
  "refresh": {
    "cadence": "Every 5 minutes",
    "description": "Clock-in alerts, role coverage, and attendance exceptions refresh from ShiftQ computed snapshots every 5 minutes."
  }
}

Normalized response envelope

All endpoints use a common outer shape so clients can treat resources consistently.

{
  "ok": true,
  "version": "v1",
  "resource": "shiftq/clock-ins",
  "groupId": "GROUP_ID",
  "locationId": "LOCATION_ID",
  "generatedAt": "ISO_TIMESTAMP",
  "data": {
    "location": {
      "id": "LOCATION_ID",
      "name": "LOCATION_NAME",
      "timezone": "IANA_TIMEZONE"
    },
    "refresh": {
      "cadence": "CADENCE_STRING",
      "description": "REFRESH_DESCRIPTION"
    }
  }
}

Common API responses

• 200 OK: request succeeded.
• 401 Unauthorized: token missing or invalid.
• 403 Forbidden: token revoked, expired, outside allowed locations, or missing the required scope.
• 404 Not Found: group, location, or resource was not found.
• 429 Too Many Requests: application rate limit exceeded.

Limits use a one-minute UTC window per Customer API application across all of its endpoints, enabled modules, and issued access tokens. Additional access tokens do not add quota. Successful responses include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, and RateLimit-Policy. A 429 also includes Retry-After. The token endpoint returns OAuth-style invalid_request, unsupported_grant_type, or generic invalid_client errors without sensitive details. The application owner receives one warning when usage first reaches 80% and one exceeded alert per window; repeated throttled requests do not generate repeated emails.