--- openapi: 3.0.3 info: title: MangoApps API description: | # MangoApps API Documentation This API provides access to the MangoApps platform, allowing you to: - Manage shifts and schedules - Get notified of changes via webhooks - Upload and retrieve demand forecasts - Perform bulk operations on shifts, assignments, and more - Mobile authentication and user management ## Authentication The API supports multiple authentication methods: ### Mobile App Authentication ``` POST /api/v1/auth/login { "email": "user@example.com", "password": "password", "otp_code": "123456" // Optional, required if 2FA is enabled } ``` Response includes `access_token` and `refresh_token` for subsequent requests. ### API Token Authentication Include the token in the Authorization header: ``` Authorization: Bearer YOUR_API_TOKEN ``` ### Service Account Authentication For service accounts, include both token and secret: ``` Authorization: Bearer YOUR_TOKEN X-API-Secret: YOUR_SECRET ``` Service accounts with the `admin` scope have full access to all API endpoints and bypass individual scope checks. Other service accounts require specific scopes (e.g., `read:shifts`, `write:attendance`) for each endpoint. ### Impersonation Token Authentication Service accounts with `impersonate` or `admin` scope can create short-lived impersonation tokens to act on behalf of specific users. This is useful for accessing user-specific data (e.g., leave balances, personal preferences) without creating separate admin endpoints. To use impersonation: 1. Create an impersonation token using your service account: ``` POST /api/v1/auth/impersonate Authorization: Bearer YOUR_SERVICE_ACCOUNT_TOKEN X-API-Secret: YOUR_SERVICE_ACCOUNT_SECRET { "user_id": 123 } ``` 2. Use the returned impersonation token for subsequent API calls: ``` Authorization: Bearer IMPERSONATION_TOKEN ``` Impersonation tokens: - Are short-lived (default: 1 hour) - Can be revoked at any time - Automatically log all access for audit purposes - Allow access to user-specific endpoints as if authenticated as that user An impersonation token can never change how the person signs in or recovers their account: changing the password, the sign-in phone, email or User ID, two-factor authentication or backup codes, API tokens, sessions or security settings answers `403` with error code `impersonation_cannot_change_account_security`, and the person must make that change from their own sign-in. While impersonation target checks are enabled for the installation, creating an impersonation token answers `403` with error code `impersonation_target_not_allowed` when the person may not be impersonated through that token: they are a Super Admin in another organization where the token's owner isn't one, they also belong to another organization the owner doesn't administer, or they are a Super Admin here and the owner isn't; the error `message` says which. The same checks run on every request of an open impersonation session, so a token whose person would now be refused stops authenticating (`401`). While the checks are disabled, none of these refusals applies. ## Rate Limiting Each API token may make 5,000 requests per hour, of which 5,000 may be searches and 1,000 uploads. Authentication calls are limited to 2,000 per hour for each network address, and requests with no valid token share 10,000 per hour for each network address. Narrower limits apply to some costly endpoints. Exceeding a limit answers `429`. Every 429 carries `Retry-After`, the seconds to wait. The platform's limits use error code `rate_limited`; a feature with a limit of its own can use its own code. Rate limit headers are included in responses, for the limit you will reach first: - `X-RateLimit-Limit`: Request limit per window - `X-RateLimit-Remaining`: Requests remaining in current window - `X-RateLimit-Reset`: Unix timestamp when window resets Wait for `Retry-After` before sending the call again. A client that keeps calling while refused can be refused for longer, by the load balancer or by thread time used. ## API Allowance (402) Every call made with an API token someone created (a personal, admin, service-account or CLI token) counts against the organization's monthly API allowance, then against purchased API credits. Once both are used up, each such call answers `402` with error code `api_credits_exhausted` (response `ApiCreditsExhausted`) on every endpoint but `POST /auth/logout` (signing out is never refused), until the allowance resets on the 1st, credits are bought, or auto top-up buys more (Admin → Billing & Payments → Credits). Enterprise plans are not limited. Calls from a signed-in browser session and from the MangoApps apps' own sign-in are neither counted nor refused, and refused calls (`401`, `402`, `403`, `429`) and server errors are not counted. ## Pagination Collections return pagination metadata and headers: - Query parameters: `page`, `per_page` - Response headers: `X-Total-Count`, `X-Total-Pages`, `X-Current-Page`, `X-Per-Page` ## Error Handling Errors follow a consistent format: ```json { "error": { "code": "error_code", "message": "Human readable message", "details": {} // Optional additional context } } ``` Validation errors return: ```json { "errors": [ { "field": "email", "message": "Email is required", "code": "validation_error" } ] } ``` ## HTTP Protocol Enhancements The API includes comprehensive HTTP protocol enhancements for optimal client performance: ### Intelligent Caching - **ETags**: Content-based versioning for efficient cache validation - **Cache-Control**: Fine-grained cache behavior control - **Conditional Requests**: Support for If-None-Match headers (304 responses) - **Vary Headers**: Content negotiation awareness ### Dynamic Navigation - **Next Actions**: Server-suggested user actions based on context - **Preload Hints**: Resources to preload for better performance - **Conditional Redirects**: Dynamic flow control based on user state - **Link Relations**: Standard HTTP Link headers for navigation ### Performance Optimization - **Response Compression**: Automatic gzip/deflate compression - **Response Timing**: Server processing metrics - **Cache Status**: Hit/miss reporting for optimization - **Size Estimation**: Bandwidth usage awareness ### Base Path and Versioning - All endpoint paths in this specification are relative. The `/api/v1` base path is provided by the `servers` section below. - When calling the API, combine the server URL with the relative path. For example: `https://dev.workforce.mangoapps.com/api/v1` + `/shifts` → `https://dev.workforce.mangoapps.com/api/v1/shifts`. - Do not include `/api/v1` in individual path keys; it is already defined at the server level for consistency across environments. ### Client Hints & Reliability - **Rate Limiting**: Request quota and reset information (429 status) - **API Versioning**: Version compatibility information - **Deprecation Warnings**: Graceful API evolution notices - **Capability Detection**: Client feature detection - **Idempotency Support**: Duplicate request prevention with Idempotency-Key - **Conditional Requests**: 304 Not Modified for cached content ### Example Enhanced Response Headers ```http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 Content-Encoding: gzip ETag: W/"abc123-def456" Cache-Control: private, max-age=300, must-revalidate Vary: Accept, Authorization, X-App-Platform Link: ; rel="preload"; as="fetch" X-Response-Time: 45.2ms X-RateLimit-Remaining: 4998 X-RateLimit-Reset: 1640995200 X-RateLimit-Limit: 5000 X-Idempotency-Cached: false X-API-Version: 1.0 ``` These enhancements provide: - **50-80% bandwidth reduction** with compression - **60-90% cache hit rates** with intelligent ETags - **2-3x faster navigation** with preload hints - **Reduced API calls** with conditional requests version: 1.0.0 contact: name: MangoApps API Support email: api-support@workforce.mangoapps.com license: name: Proprietary servers: - url: https://api.workforce.mangoapps.com/api/v1 description: Production - Common API - url: https://dev.workforce.mangoapps.com/api/v1 description: Development - Common API - url: https://{business}.workforce.mangoapps.com/api/v1 description: Production - Business API variables: business: default: demo description: Business subdomain (e.g., officechat, acmecorp) examples: - officechat - acmecorp - retailstore - url: https://{business}.dev.workforce.mangoapps.com/api/v1 description: Development - Business API variables: business: default: demo description: Business subdomain for development security: - BearerAuth: [] - ServiceAccountAuth: [] paths: "/changelog_entries": get: tags: - Changelog summary: List changelog entries description: "Retrieve a list of changelog entries. This endpoint is for internal use only \nand requires either internal API credentials or a changelog secret.\n" security: - InternalAPI: [] - ChangelogSecret: [] responses: '200': description: List of changelog entries content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: "$ref": "#/components/schemas/ChangelogEntry" meta: type: object properties: total_count: type: integer example: 25 published_count: type: integer example: 20 latest_version: type: string example: '1.6' '401': "$ref": "#/components/responses/Unauthorized" post: tags: - Changelog summary: Create changelog entry description: "Create a new changelog entry. This endpoint is for internal use only \nand requires either internal API credentials or a changelog secret.\n" security: - InternalAPI: [] - ChangelogSecret: [] requestBody: required: true content: application/json: schema: type: object required: - changelog_entry properties: changelog_entry: "$ref": "#/components/schemas/ChangelogEntryInput" responses: '201': description: Changelog entry created successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Changelog entry created successfully data: "$ref": "#/components/schemas/ChangelogEntryResponse" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '422': description: Validation error content: application/json: schema: type: object properties: success: type: boolean example: false message: type: string example: Failed to create changelog entry errors: type: array items: type: string example: - Title can't be blank - Content can't be blank "/businesses/by_email": post: servers: - url: https://api.workforce.mangoapps.com/api/v1 description: Production - Common API - url: https://dev.workforce.mangoapps.com/api/v1 description: Development - Common API tags: - Business Discovery summary: Get businesses by user email description: | Find the tenants a user's email address can sign in to. This backs the workspace picker after mobile's email-entry screen, and is the JSON twin of the web `POST /find_companies` flow. Prefer POST over the GET below: the query-string form writes the address into access logs and error-tracker breadcrumbs. Throttled at 20 requests/minute per IP and 10/minute per email address. security: [] requestBody: required: true content: application/json: schema: type: object required: - email properties: email: type: string format: email example: user@officechat.com responses: '200': description: | Lookup completed. An empty `businesses` array means the address is unknown OR has no active tenants — the two are not distinguished. content: application/json: schema: "$ref": "#/components/schemas/BusinessDiscoveryResult" '400': description: Missing or blank email content: application/json: schema: "$ref": "#/components/schemas/Error" '429': description: Rate limit exceeded get: servers: - url: https://api.workforce.mangoapps.com/api/v1 description: Production - Common API - url: https://dev.workforce.mangoapps.com/api/v1 description: Development - Common API tags: - Business Discovery summary: Get businesses by user email (query-string form) deprecated: true description: | Kept for existing clients. Use `POST /businesses/by_email` instead — a query string puts the email address into access logs and error-tracker breadcrumbs. Identical behaviour and response otherwise. security: [] parameters: - name: email in: query required: true description: User's email address schema: type: string format: email example: user@officechat.com responses: '200': description: | Lookup completed. An empty `businesses` array means the address is unknown OR has no active tenants — the two are not distinguished. content: application/json: schema: "$ref": "#/components/schemas/BusinessDiscoveryResult" '400': description: Missing or blank email content: application/json: schema: "$ref": "#/components/schemas/Error" '429': description: Rate limit exceeded "/businesses/lookup": get: servers: - url: https://api.workforce.mangoapps.com/api/v1 description: Production - Common API - url: https://dev.workforce.mangoapps.com/api/v1 description: Development - Common API tags: - Business Discovery summary: Search businesses by company name description: | Search for businesses using partial or full company name matching. Returns up to 10 matching businesses. Matching ignores case AND punctuation on both sides — spaces, apostrophes, hyphens, periods — so `Oreilly`, `O'Reilly` and `oreilly auto parts` all find "O'Reilly Auto Parts". A term containing no letter or digit at all (e.g. `'''`) is rejected with `missing_company_name`, exactly like an absent parameter. Useful for company name lookup and business directory features. security: [] parameters: - name: company_name in: query required: true description: Full or partial company name to search for schema: type: string example: Office Chat responses: '200': description: Businesses found content: application/json: schema: type: object properties: businesses: type: array items: type: object properties: id: type: integer example: 456 name: type: string example: Office Chat Solutions subdomain: type: string example: officechat logo_url: type: string nullable: true description: | Absolute logo URL, or null when unattached. Served from the matched tenant's OWN host — this endpoint searches across tenants, so it is not the requesting host. example: https://acme.workforce.mangoapps.com/rails/active_storage/blobs/redirect/…/logo.png api_base_url: type: string description: | Origin the client should send the subsequent login request to, and the disambiguator to show under each company name in a search list. Identical to the `api_base_url` that `/businesses/by_email` returns for the same business `id` — both endpoints render through one serializer. Already carries the environment suffix (-dev / -qa / -staging; none in production), so clients must not rebuild the host from `subdomain` themselves. example: https://officechat.workforce.mangoapps.com timezone: type: string example: America/New_York industry: type: string description: | Tenant industry, or an empty string when unset — it is emitted as "" rather than omitted, so treat empty as absent. Not a reliable subtitle; use `api_base_url`. example: '' hosted_elsewhere: type: boolean description: | Present (true) only for a workspace hosted on another MangoApps deployment, such as Europe. Its `id` is its id there, `api_base_url` is where to sign in, `logo_url` is null and `timezone` is absent. This deployment's own workspaces come first. example: true deployment: type: string description: Present only with `hosted_elsewhere`. The deployment's label, e.g. `eu`. example: eu total_count: type: integer example: 2 description: Number of businesses found (max 10) search_term: type: string example: Office Chat description: The search term used '400': description: Missing company name parameter content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: No businesses found matching the search term content: application/json: schema: "$ref": "#/components/schemas/Error" "/businesses/validate_subdomain": get: servers: - url: https://api.workforce.mangoapps.com/api/v1 description: Production - Common API - url: https://dev.workforce.mangoapps.com/api/v1 description: Development - Common API tags: - Business Discovery summary: Validate business subdomain exists description: Check if a business subdomain is available and valid security: [] parameters: - name: subdomain in: query required: true description: Business subdomain to validate schema: type: string example: officechat responses: '200': description: Validation result content: application/json: schema: type: object properties: exists: type: boolean example: true subdomain: type: string example: officechat business_name: type: string example: Office Chat Solutions hosted_elsewhere: type: boolean description: | Present (true) only when the workspace is hosted on another MangoApps deployment, such as Europe. `exists` stays false — it means "on this deployment" — and `api_base_url` is where to sign in. example: true api_base_url: type: string description: | The origin to sign in at, when the workspace exists here or is hosted elsewhere. Absent when it is unknown. example: https://acme.onemango.com '400': description: Missing subdomain parameter content: application/json: schema: "$ref": "#/components/schemas/Error" "/auth/login": post: tags: - Authentication summary: Login for mobile apps description: "Authenticate user and return access/refresh tokens.\n\n**Session Cookie Support:** In addition to returning API tokens, this endpoint \nalso establishes a Rails session and sets a session cookie (`_workforce_session_*`). \nThis allows the session cookie to be used for web page access without requiring \na separate web login. The session cookie is automatically set by the server and \nmanaged by HTTP clients.\n\n**Use Cases:**\n- Mobile apps: Use the access_token for API calls\n- Web views in mobile apps: The session cookie enables seamless web page access\n- Hybrid apps: Use either API tokens or session cookie as needed\n" security: [] requestBody: required: true content: application/json: schema: type: object required: - email - password properties: email: type: string format: email example: user@example.com password: type: string format: password example: password123 otp_code: type: string description: Two-factor authentication code (required if 2FA enabled) example: '123456' responses: '200': description: Login successful content: application/json: schema: type: object properties: access_token: type: string description: JWT access token refresh_token: type: string description: Refresh token for getting new access tokens expires_in: type: integer description: Access token expiry in seconds token_type: type: string example: Bearer user: "$ref": "#/components/schemas/User" business: "$ref": "#/components/schemas/Business" _meta: "$ref": "#/components/schemas/HttpEnhancementMeta" '401': description: Authentication failed content: application/json: schema: oneOf: - "$ref": "#/components/schemas/Error" - type: object properties: error: type: object properties: code: type: string description: 'account_locked: too many failed sign-in attempts (each wrong password counts); no tokens are issued' enum: - two_factor_required - invalid_otp - invalid_credentials - account_locked message: type: string details: type: object properties: requires_2fa: type: boolean '403': description: | The credentials were right and no tokens are issued until the person finishes a step on the web. two_factor_setup_required: the organization requires two-factor authentication of this person (everyone, or their role) and they have not set it up, or they started setting it up and never confirmed it. Open details.setup_url (the organization's web sign-in, which leads to setup), then sign in again; the next sign-in asks for otp_code. password_expired: the password is past the organization's expiry period; details.change_url is where it is changed. content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - two_factor_setup_required - password_expired message: type: string details: type: object properties: requires_2fa_setup: type: boolean setup_url: type: string change_url: type: string "/auth/hub_sso": post: tags: - Authentication summary: Sign in with a MangoApps Hub token (mobile apps) description: | Exchanges a signed MangoApps Hub token for access and refresh tokens, like /auth/login. A locked account (too many failed sign-in attempts) is refused with account_locked, and no tokens are issued. security: [] requestBody: required: true content: application/json: schema: type: object required: - token properties: token: type: string description: Signed MangoApps Hub token business_id: type: integer description: Organization to sign in to responses: '200': description: Signed in. The same token fields as /auth/login, plus sso_provider. '401': description: Sign-in refused content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - no_token - not_configured - invalid_token - expired_token - nonce_reused - domain_mismatch - user_deactivated - jit_disabled - jit_domain_blocked - provisioning_failed - service_account_blocked - account_locked message: type: string details: type: object properties: suggestion: type: string "/auth/login_config": get: tags: - Authentication - Mobile summary: Get login configuration for business description: | Returns complete login configuration for a business including available authentication methods, SSO providers, security settings, and API endpoints. This endpoint provides all information needed to render a mobile login screen. SSO Provider Support: - Multiple SSO providers of the same type are supported (e.g., multiple Google OAuth2 configs) - Each provider has a unique ID that should be used as the `provider_id` parameter - Use `channel_support` and `mobile_supported`/`web_supported` to filter providers appropriate for the client security: [] parameters: - name: business_id in: query required: true schema: type: integer description: Business ID to get login configuration for example: 123 responses: '200': description: Login configuration retrieved successfully content: application/json: schema: "$ref": "#/components/schemas/LoginConfiguration" '404': description: Business not found content: application/json: schema: "$ref": "#/components/schemas/Error" "/auth/sso/initiate": post: tags: - Authentication - SSO - Mobile summary: Initiate SSO authentication flow description: | Initiates SSO authentication flow for mobile applications. Returns an authorization URL that should be opened in a web view or external browser. The mobile app should handle the callback and extract the authorization code for token exchange. Provider Selection: 1. Call `/auth/login_config` to get available SSO providers 2. Display providers to user (multiple providers of same type may exist) 3. Use the selected provider's `id` as the `provider_id` in this request 4. For mobile, choose providers with `mobile_supported: true` security: [] requestBody: required: true content: application/json: schema: type: object required: - business_id - provider_id properties: business_id: type: integer description: Business ID for SSO authentication example: 123 provider_id: type: string description: SSO provider ID from login configuration example: '2' redirect_uri: type: string description: Optional redirect URI (HTTPS URL for Universal Links/App Links - Google OAuth does not support custom URL schemes) example: https://workforce.mangoapps.com/mobile/sso-callback app_redirect_uri: type: string description: | Desktop only. Where the callback page sends the browser once the IdP is finished — never sent to the IdP itself. Accepted forms are a registered custom scheme (`mangoappsdesktop://`, `mangoappsmessengerschema://`) or a loopback callback the app serves itself: `http://127.0.0.1:/sso-callback` or `http://[::1]:/sso-callback`, with no query, fragment, or credentials and a port in 1-65535. Anything else is dropped. Check the echoed `app_redirect_uri` in the response to see whether the value survived. example: http://127.0.0.1:52341/sso-callback code_challenge: type: string description: | The app's own PKCE challenge (RFC 7636, RFC 8252 §8.1): the base64url SHA-256 (43 characters, no padding) of a random `code_verifier` the app keeps and presents to `/auth/sso/exchange`. The server stores only the challenge, bound to the returned `state`. Optional today; once the platform requires it, a request without one is refused with `pkce_required`. example: E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM code_challenge_method: type: string enum: - S256 description: Only `S256` is accepted. Defaults to `S256` when a challenge is sent. responses: '200': description: SSO flow initiated successfully content: application/json: schema: "$ref": "#/components/schemas/SsoInitiateResponse" '400': description: | Invalid request parameters. `pkce_required` — the platform requires the app's `code_challenge` and none was sent. `invalid_pkce` — the challenge is not a 43-character base64url SHA-256, or the method is not `S256`. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Business or SSO provider not found content: application/json: schema: "$ref": "#/components/schemas/Error" '503': description: SSO provider temporarily unavailable content: application/json: schema: "$ref": "#/components/schemas/Error" "/auth/sso/exchange": post: tags: - Authentication - SSO - Mobile summary: Exchange authorization code for access tokens description: "Exchanges the authorization code received from SSO provider for access and refresh tokens.\nThis completes the SSO authentication flow and returns tokens that can be used for API access.\n\n**Session Cookie Support:** In addition to returning API tokens, this endpoint \nalso establishes a Rails session and sets a session cookie (`_workforce_session_*`). \nThis allows the session cookie to be used for web page access without requiring \na separate web login. The session cookie is automatically set by the server and \nincluded in the response headers - no client-side code changes are needed to receive it.\n\n**Use cases for session cookie:**\n- Web views in mobile apps: The session cookie enables seamless web page access\n- Hybrid apps: Use either API tokens or session cookie as needed\n- Native mobile + web integration: Access web content without re-login prompts\n" security: [] requestBody: required: true content: application/json: schema: type: object required: - business_id - provider_id - code - state properties: business_id: type: integer description: Business ID for SSO authentication example: 123 provider_id: type: string description: SSO provider ID from login configuration example: '2' code: type: string description: Authorization code from SSO provider callback example: 4/0AX4XfWjE... state: type: string description: State parameter from SSO initiate response example: abc123def456 code_verifier: type: string description: | The PKCE verifier (43-128 characters of `A-Z a-z 0-9 - . _ ~`) whose S256 challenge the app sent to `/auth/sso/initiate`. Required whenever the initiate request carried a `code_challenge`; a missing or wrong verifier is refused with `invalid_grant` and the state is spent. example: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk responses: '200': description: SSO authentication completed successfully content: application/json: schema: "$ref": "#/components/schemas/SsoExchangeResponse" '400': description: | `invalid_state` — the state is unknown, expired or already used, or it was issued for another business or another provider (a state is bound to the `business_id` AND `provider_id` it was initiated with; restart the flow). `invalid_grant` — the state was issued with a PKCE `code_challenge` and the `code_verifier` is missing or does not match it. `token_exchange_failed` — the provider refused the code. `missing_parameters` — a required field is blank. content: application/json: schema: "$ref": "#/components/schemas/Error" '401': description: | `sso_verification_failed` — the provider's ID token did not verify (signature, issuer, audience, expiry or nonce); a failed sign-in, not a missing account. `email_not_verified` — the provider did not vouch for the email and no account is linked to this identity yet. `user_not_found` — no active account for this person and none was provisioned. `account_locked` — the account is locked after too many failed sign-in attempts; no token is minted. `user_deactivated` — the account cannot sign in. content: application/json: schema: "$ref": "#/components/schemas/Error" '403': description: | `user_not_authorized` — the person's membership in this business has ended, or the account may not sign in here. content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Business or SSO provider not found (`sso_provider_not_found`) content: application/json: schema: "$ref": "#/components/schemas/Error" "/auth/refresh": post: tags: - Authentication summary: Refresh access token description: | Get a new access token using refresh token. Not the Office add-in's refresh token, which is exchanged at `/auth/office_addin/refresh` for the add-in's own token. security: [] requestBody: required: true content: application/json: schema: type: object required: - refresh_token properties: refresh_token: type: string description: Valid refresh token responses: '200': description: Token refreshed successfully content: application/json: schema: type: object properties: access_token: type: string expires_in: type: integer token_type: type: string example: Bearer '401': "$ref": "#/components/responses/Unauthorized" "/auth/logout": post: tags: - Authentication summary: Logout and revoke tokens description: Revoke current access token and optionally refresh token requestBody: content: application/json: schema: type: object properties: refresh_token: type: string description: Refresh token to revoke (optional) responses: '200': description: Logged out successfully content: application/json: schema: type: object properties: message: type: string example: Logged out successfully '401': "$ref": "#/components/responses/Unauthorized" "/auth/webview_token": post: tags: - Authentication summary: Mint a one-time hand-off into a web session description: | A native app (mobile or desktop) turns its API sign-in into a browser session: it asks here with its Bearer token, then opens `/m/login/native` with the token, which signs the browser in. The token is signed, works once and expires after 60 seconds. Only the access token a sign-in door gave the person, with its full permissions, may ask — the browser session it starts has no second factor of its own. Personal, integration and CLI tokens, service accounts, impersonation tokens and a browser's own cookie session are refused, and so is a locked or deactivated account. **Token scopes:** none beyond being the sign-in access token. security: - BearerAuth: [] responses: '200': description: The hand-off token. content: application/json: schema: type: object required: - webview_token - expires_in properties: webview_token: type: string description: Pass it to `/m/login/native` within a minute. It is redeemed once. expires_in: type: integer example: 60 '401': description: "`authentication_required` or `invalid_token` (no valid Bearer token), or `webview_token_requires_access_token` (the request carried only a browser session cookie)." content: application/json: schema: "$ref": "#/components/schemas/Error" '403': description: "`webview_token_impersonation_not_allowed`, `webview_token_service_account_not_allowed`, `webview_token_requires_sign_in_token` (a personal, integration or CLI token, or one with narrowed scopes), `webview_token_account_locked` or `webview_token_account_inactive`." content: application/json: schema: "$ref": "#/components/schemas/Error" "/auth/profile": get: tags: - Authentication summary: Get enhanced user profile description: "Retrieve comprehensive user profile including security info, preferences, \npermissions, and feature flags. This endpoint provides more detailed \ninformation than the basic /users/me endpoint.\n" responses: '200': description: Profile retrieved successfully content: application/json: schema: type: object properties: user: "$ref": "#/components/schemas/EnhancedUser" business: "$ref": "#/components/schemas/Business" security: "$ref": "#/components/schemas/SecurityInfo" preferences: type: object description: User preferences and settings permissions: type: array items: type: string description: User permissions feature_flags: type: object description: Available feature flags for user custom_fields: type: array description: The organization's own profile fields on the caller that they may see on themself, as `GET /users/me` lists them. Empty while custom fields are off for the organization. items: "$ref": "#/components/schemas/ProfileCustomField" personnel_file_copy_request: type: object nullable: true description: The caller's waiting request for a copy of their personnel file (POST /profile/actions request_personnel_file_copy), or null. Null under View-as. properties: id: type: integer status: type: string example: requested requested_at: type: string format: date due_on: type: string format: date personnel_file_copy_sent_at: type: string format: date-time nullable: true description: When HR recorded sending the caller the last copy of their personnel file they asked for (the web and phone "HR sent you a copy on …"), or null. Null under View-as. '401': "$ref": "#/components/responses/Unauthorized" patch: tags: - Authentication summary: Update user profile description: | Update user profile information including preferences and notification settings. Called with an impersonation token, a request whose `phone` (or an `email` or `userid` value) differs from the stored one answers 403 `impersonation_cannot_change_account_security`; sending the stored values back unchanged is not refused. When employee self-service profile editing is turned off for the organization, a caller below administrator gets 403 `self_service_disabled`. requestBody: required: true content: application/json: schema: type: object properties: first_name: type: string example: John last_name: type: string example: Doe phone: type: string example: "+1234567890" time_zone: type: string example: America/New_York language: type: string nullable: true description: | The person's own language, one of the organization's languages. Blank or `null` is "Not set" — content follows their place's language (Knowledge Layer P4). The value GET /auth/profile returned for someone who never chose one (`language_set: false`) is their place's language; posting it back changes nothing. Their own stored value is always accepted back. example: fr preferences: type: object description: User preferences to update notification_preferences: type: object description: Notification preferences to update responses: '200': description: Profile updated successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Profile updated successfully user: "$ref": "#/components/schemas/EnhancedUser" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/ImpersonationAccountSecurityForbidden" '422': "$ref": "#/components/responses/ValidationError" "/auth/change_password": post: tags: - Authentication summary: Change user password description: | Change the current user's password with proper verification. When called with an API token (personal or service account) and `revoke_other_sessions: true`, the account's other active API tokens are revoked. A caller authenticated by a web session revokes nothing, and `revoked_sessions` reports what actually ran. An impersonation token can't change the password at all: it gets 403 `impersonation_cannot_change_account_security`. requestBody: required: true content: application/json: schema: type: object required: - current_password - new_password - new_password_confirmation properties: current_password: type: string description: Current password for verification new_password: type: string description: New password (minimum 6 characters) new_password_confirmation: type: string description: Confirmation of new password revoke_other_sessions: type: boolean default: false description: Send JSON `true` to revoke the account's other active API tokens. Honoured only for an API token caller (personal or service account). responses: '200': description: Password changed successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Password changed successfully revoked_sessions: type: boolean description: True when this call revoked the account's other API tokens (see `revoked_sessions_count`), false when no revocation ran. revoked_sessions_count: type: integer description: Number of other API tokens this call revoked; 0 when none were revoked. example: 2 '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/ImpersonationAccountSecurityForbidden" '422': "$ref": "#/components/responses/ValidationError" "/auth/password_reset/forgot_password": post: tags: - Authentication - Password Reset summary: Request password reset description: | Initiate password reset process by sending a reset link to the user's email. Returns a generic success message regardless of whether the email exists (security best practice). security: [] requestBody: required: true content: application/json: schema: type: object required: - email properties: email: type: string format: email description: Email address of the account example: user@example.com responses: '200': description: Password reset email sent (or email doesn't exist - generic response for security) content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: If an account exists with this email, you will receive password reset instructions shortly. email: type: string example: user@example.com '400': "$ref": "#/components/responses/BadRequest" "/auth/password_reset/validate_token": get: tags: - Authentication - Password Reset summary: Validate password reset token description: | Check if a password reset token is valid and not expired. Tokens expire after 6 hours. security: [] parameters: - name: token in: query required: true schema: type: string description: Password reset token from email example: abc123xyz789 responses: '200': description: Token is valid content: application/json: schema: type: object properties: valid: type: boolean example: true email: type: string example: user@example.com expires_at: type: string format: date-time example: '2025-10-10T20:00:00Z' '401': description: Token is invalid or expired content: application/json: schema: "$ref": "#/components/schemas/Error" example: error: code: invalid_or_expired_token message: Password reset token is invalid or has expired. "/auth/password_reset/reset_password": post: tags: - Authentication - Password Reset summary: Reset password with token description: | Complete the password reset process using a valid reset token. A successful reset revokes every API token the account holds, in every organization (sign-in and refresh tokens, personal and CLI tokens), so each device or integration must sign in again or be issued a new token. security: [] requestBody: required: true content: application/json: schema: type: object required: - token - password - password_confirmation properties: token: type: string description: Password reset token from email example: abc123xyz789 password: type: string format: password description: New password (minimum 6 characters) example: newSecurePassword123 password_confirmation: type: string format: password description: Confirmation of new password example: newSecurePassword123 revoke_all_sessions: type: boolean deprecated: true description: Ignored. A successful reset always revokes every API token the account holds. responses: '200': description: Password reset successful content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Your password has been reset successfully. email: type: string example: user@example.com revoked_all_sessions: type: boolean description: True on success. Every API token the account held has been revoked. example: true '400': description: Invalid request (passwords don't match, too weak, etc.) content: application/json: schema: "$ref": "#/components/schemas/Error" '401': description: Token is invalid or expired content: application/json: schema: "$ref": "#/components/schemas/Error" '422': "$ref": "#/components/responses/ValidationError" "/auth/connections": get: tags: - Authentication summary: List my connected assistants description: | The assistants that can act for the caller — MCP clients they signed in to (one row per client), their personal API tokens and their Office add-in sign-ins (one row per Word or Excel pane that signed in) — with what each may do in plain words, and the caller's latest assistant activity. security: - BearerAuth: [] responses: '200': description: The caller's connections content: application/json: schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/Connection" recent_activity: type: array description: The caller's latest assistant tool calls, newest first (at most 10). items: type: object properties: at: type: string format: date-time client: type: string nullable: true example: Claude tool: type: string example: list_workspace_messages outcome: type: string enum: - started - completed - failed - preview - replayed - denied success: type: boolean meta: type: object properties: connections_enabled: type: boolean description: False when the organization has turned assistant connections off; nothing listed can act until it is turned back on. '401': description: Authentication required "/auth/connections/{kind}/{id}": delete: tags: - Authentication summary: Revoke one of my connected assistants description: | Disconnects an MCP client (every grant the caller gave it in this organization, with its pending authorization codes), revokes a personal API token, or signs out an Office add-in sign-in (its refresh token and every live add-in access token the caller holds here — the add-in's own sign-out). It stops working at once; a client can be connected again by signing in from it. Needs a token with the `write:connections` scope — the app's own sign-in and the CLI carry it — so a narrow token cannot revoke the caller's other credentials. security: - BearerAuth: [] parameters: - name: kind in: path required: true schema: type: string enum: - oauth - token - office_addin - name: id in: path required: true schema: type: integer description: The client's or token's id, as listed. responses: '200': description: Revoked content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Claude is disconnected revoked: type: object properties: name: type: string kind: type: string enum: - oauth - token - office_addin revoked: type: integer description: Grants or tokens revoked. '401': description: Authentication required '403': description: | The token has no `write:connections` scope (`insufficient_permissions`), or it is an impersonation session, which cannot revoke (`impersonation_cannot_change_account_security`). '404': description: Not one of the caller's connections "/auth/office_addin/device": post: tags: - Authentication summary: Start the Office add-in's sign-in description: | Issues a device code (kept by the add-in) and a short user code the person checks on the sign-in page, bound to the workspace whose address the request was sent to. Open `verification_url_complete` in the person's browser (or show `verification_url` and the code to type on any device), then poll `/auth/office_addin/token` every `interval` seconds until `expires_in` runs out. security: [] responses: '200': description: A code to allow content: application/json: schema: type: object properties: device_code: type: string description: Secret. Sent only in the body of `/auth/office_addin/token`. user_code: type: string example: ABCD-EFGH verification_url: type: string example: https://acme.workforce.mangoapps.com/auth/office-addin verification_url_complete: type: string example: https://acme.workforce.mangoapps.com/auth/office-addin?code=ABCD-EFGH expires_in: type: integer example: 600 interval: type: integer example: 5 '422': description: "`workspace_required` — the address names no MangoApps workspace." content: application/json: schema: "$ref": "#/components/schemas/Error" '429': description: Too many sign-ins started from this address. "/auth/office_addin/token": post: tags: - Authentication summary: Collect the Office add-in's sign-in description: | Poll with the device code until the person allows or denies the sign-in. Once allowed, the first poll returns a one-hour access token and a 30-day refresh token; every later poll of the same code answers 410. The tokens are minted then — never stored in plaintext waiting for a poll — and the response is not cacheable. security: [] requestBody: required: true content: application/json: schema: type: object required: - device_code properties: device_code: type: string responses: '200': description: Signed in content: application/json: schema: type: object properties: status: type: string example: approved access_token: type: string refresh_token: type: string token_type: type: string example: Bearer expires_in: type: integer example: 3600 scopes: type: array items: type: string example: - read:contracts - write:contracts - destructive:contracts - read:drive - write:drive user: type: object properties: id: type: integer name: type: string email: type: string nullable: true business: type: object properties: id: type: integer name: type: string subdomain: type: string nullable: true '202': description: Not allowed yet — poll again after `interval` seconds. content: application/json: schema: type: object properties: status: type: string example: authorization_pending '400': description: "`invalid_request` — no device_code." '403': description: | `status: denied` — the person chose Deny, or their account may no longer sign in (`error.code: access_denied`). '404': description: "`invalid_device_code` — not a code this door issued." '410': description: "`status: expired` — the code expired or was already collected (`error.code: expired_token`)." '429': description: Polled too often from this address; poll more slowly. "/auth/office_addin/refresh": post: tags: - Authentication summary: Refresh the Office add-in's access token description: | A new one-hour access token for the add-in's live refresh token, while its person may still sign in. Only the add-in's refresh token is accepted here, and the app sign-in's `/auth/refresh` does not accept it. security: [] requestBody: required: true content: application/json: schema: type: object required: - refresh_token properties: refresh_token: type: string responses: '200': description: A new access token content: application/json: schema: type: object properties: access_token: type: string token_type: type: string example: Bearer expires_in: type: integer example: 3600 '401': description: "`invalid_refresh_token` — the sign-in has ended; sign in again." content: application/json: schema: "$ref": "#/components/schemas/Error" "/auth/office_addin/sign_out": post: tags: - Authentication summary: Sign the Office add-in out description: | Revokes the add-in's own access token (the Bearer header) and refresh token (the body) — either is enough, so a pane whose access token ran out can still sign out. Any other token is left alone: a token pasted into the add-in is never revoked here. security: [] parameters: - name: Authorization in: header required: false schema: type: string example: Bearer requestBody: required: false content: application/json: schema: type: object properties: refresh_token: type: string responses: '200': description: Signed out content: application/json: schema: type: object properties: signed_out: type: boolean example: true '401': description: "`invalid_token` — neither credential is an Office add-in sign-in." content: application/json: schema: "$ref": "#/components/schemas/Error" "/auth/sessions": get: tags: - Authentication summary: List active sessions description: | Retrieve a list of all active sessions (API tokens) for the current user. Includes session details like device info, location, and last activity. parameters: - "$ref": "#/components/parameters/Page" - "$ref": "#/components/parameters/PerPage" responses: '200': description: Sessions retrieved successfully content: application/json: schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/Session" meta: type: object properties: current_session_id: type: integer description: ID of the current session total_active_sessions: type: integer description: Total number of active sessions pagination: "$ref": "#/components/schemas/PaginationMeta" '401': "$ref": "#/components/responses/Unauthorized" "/auth/sessions/current": get: tags: - Authentication summary: Get current session details description: Retrieve detailed information about the current active session responses: '200': description: Current session retrieved successfully content: application/json: schema: type: object properties: session: "$ref": "#/components/schemas/DetailedSession" is_current_session: type: boolean example: true '401': "$ref": "#/components/responses/Unauthorized" "/auth/sessions/revoke_all": post: tags: - Authentication summary: Revoke all other sessions description: | Revoke all active sessions except the current one. Useful for security when a user suspects their account may be compromised. Needs a token with the `write:connections` scope. responses: '200': description: Other sessions revoked successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Successfully revoked 3 other sessions revoked_count: type: integer description: Number of sessions revoked current_session_preserved: type: boolean example: true '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/CredentialsWriteForbidden" "/auth/sessions/{id}": get: tags: - Authentication summary: Get session details description: Retrieve detailed information about a specific session parameters: - name: id in: path required: true schema: type: integer description: Session ID responses: '200': description: Session details retrieved successfully content: application/json: schema: type: object properties: session: "$ref": "#/components/schemas/DetailedSession" '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" delete: tags: - Authentication summary: Revoke specific session description: | Revoke a specific session by ID. Cannot revoke the current session - use the logout endpoint instead. Needs a token with the `write:connections` scope. parameters: - name: id in: path required: true schema: type: integer description: Session ID to revoke responses: '200': description: Session revoked successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Session revoked successfully revoked_session: "$ref": "#/components/schemas/Session" '400': description: Cannot revoke current session content: application/json: schema: "$ref": "#/components/schemas/Error" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/CredentialsWriteForbidden" '404': "$ref": "#/components/responses/NotFound" "/auth/2fa/status": get: tags: - Two-Factor Authentication summary: Get 2FA status description: Retrieve the current two-factor authentication status and configuration responses: '200': description: 2FA status retrieved successfully content: application/json: schema: type: object properties: two_factor_enabled: type: boolean description: Whether 2FA is currently enabled two_factor_status: type: string enum: - disabled - pending_setup - pending_confirmation - enabled description: Current 2FA setup status setup_required: type: boolean description: Whether 2FA setup is required by organization policy backup_codes_count: type: integer description: Number of remaining backup codes setup_at: type: string format: date-time description: When 2FA setup was initiated confirmed_at: type: string format: date-time description: When 2FA was confirmed and enabled '401': "$ref": "#/components/responses/Unauthorized" "/auth/2fa/setup": post: tags: - Two-Factor Authentication summary: Setup 2FA description: | Initiate two-factor authentication setup. Returns QR code URI and backup codes. Requires current password for verification. requestBody: required: true content: application/json: schema: type: object required: - current_password properties: current_password: type: string description: Current password for verification responses: '200': description: 2FA setup initiated successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Two-factor authentication setup initiated qr_code_uri: type: string description: QR code URI for authenticator apps secret: type: string description: Secret key for manual entry backup_codes: type: array items: type: string description: Backup codes for account recovery next_step: type: string description: Instructions for next step '400': description: 2FA already enabled or invalid request content: application/json: schema: "$ref": "#/components/schemas/Error" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/CredentialsWriteForbidden" "/auth/2fa/verify": post: tags: - Two-Factor Authentication summary: Verify and enable 2FA description: | Complete 2FA setup by verifying a code from the authenticator app. This enables 2FA for the user account. requestBody: required: true content: application/json: schema: type: object required: - code properties: code: type: string description: 6-digit verification code from authenticator app example: '123456' responses: '200': description: 2FA enabled successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Two-factor authentication enabled successfully two_factor_enabled: type: boolean example: true backup_codes: type: array items: type: string description: Backup codes for account recovery '400': description: Invalid code or 2FA not setup content: application/json: schema: "$ref": "#/components/schemas/Error" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/CredentialsWriteForbidden" "/auth/2fa/disable": post: tags: - Two-Factor Authentication summary: Disable 2FA description: | Disable two-factor authentication for the user account. Requires current password and either a 2FA code or backup code. requestBody: required: true content: application/json: schema: type: object required: - current_password properties: current_password: type: string description: Current password for verification code: type: string description: 6-digit verification code from authenticator app example: '123456' backup_code: type: string description: Backup code (alternative to verification code) example: a1b2c3d4 responses: '200': description: 2FA disabled successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Two-factor authentication disabled successfully two_factor_enabled: type: boolean example: false '400': description: 2FA not enabled or invalid request content: application/json: schema: "$ref": "#/components/schemas/Error" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/CredentialsWriteForbidden" "/auth/2fa/backup_codes": get: tags: - Two-Factor Authentication summary: Get backup codes (retired verb) deprecated: true description: | Retired: a GET carried the account password in the URL, where proxy and load-balancer logs, browser history and Referer headers keep it. Answers 405 naming the POST below (or 400 `password_in_url` when the URL carries `current_password`). responses: '400': description: "`password_in_url` — the URL carried `current_password`" content: application/json: schema: "$ref": "#/components/schemas/Error" '405': description: "`method_not_allowed` — read backup codes with POST" content: application/json: schema: "$ref": "#/components/schemas/Error" post: tags: - Two-Factor Authentication summary: Get backup codes description: | Retrieve current backup codes for 2FA recovery. Requires the current password in the request body (a `current_password` in the URL is refused with `password_in_url`) and a token carrying `write:connections`. Each read is recorded on the person's activity log. requestBody: required: true content: application/json: schema: type: object required: - current_password properties: current_password: type: string description: Current password for verification responses: '200': description: Backup codes retrieved successfully content: application/json: schema: type: object properties: backup_codes: type: array items: type: string description: Current backup codes codes_count: type: integer description: Number of backup codes warning: type: string description: Security warning about backup codes '400': description: 2FA not enabled content: application/json: schema: "$ref": "#/components/schemas/Error" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/CredentialsWriteForbidden" "/auth/2fa/regenerate_backup_codes": post: tags: - Two-Factor Authentication summary: Regenerate backup codes description: | Generate new backup codes, invalidating all previous codes. Requires current password for security. requestBody: required: true content: application/json: schema: type: object required: - current_password properties: current_password: type: string description: Current password for verification responses: '200': description: Backup codes regenerated successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Backup codes regenerated successfully backup_codes: type: array items: type: string description: New backup codes warning: type: string description: Warning about old codes being invalidated '400': description: 2FA not enabled content: application/json: schema: "$ref": "#/components/schemas/Error" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/CredentialsWriteForbidden" "/auth/passwordless/request": post: tags: - Passwordless Authentication summary: Request passwordless authentication (unavailable) deprecated: true description: | Not available. This endpoint used to accept a request for a magic link, email code or SMS code but never delivered one, so no request could end in a sign-in. It now issues nothing and answers every request, whatever its body, with the same `403 feature_disabled`. `GET /auth/login_config` reports `login_methods.passwordless.enabled: false`. Sign in with `POST /auth/login` or single sign-on. `POST /auth/passwordless/verify` is unaffected: it still redeems sign-in links issued elsewhere. security: [] responses: '403': description: Passwordless sign-in is not available. The same body is returned for every request. content: application/json: schema: "$ref": "#/components/schemas/Error" example: error: code: feature_disabled message: Sign-in links and codes are not available through the app. Sign in with your password or single sign-on. '429': description: Too many requests for this address or from this IP content: application/json: schema: "$ref": "#/components/schemas/Error" "/auth/passwordless/verify": post: tags: - Passwordless Authentication summary: Verify passwordless authentication token description: | Verify a passwordless authentication token and receive API access tokens. Accepts magic-link tokens only, and each token signs in once. Six-digit email and SMS codes belong to the web and phone sign-in doors that sent them and are answered here as an unknown token (401 invalid_token). security: [] requestBody: required: true content: application/json: schema: type: object required: - token properties: token: type: string description: Authentication token from email/SMS example: abc123def456 responses: '200': description: Authentication successful content: application/json: schema: type: object properties: access_token: type: string description: API access token refresh_token: type: string description: Token refresh token expires_in: type: integer description: Token expiration in seconds example: 3600 token_type: type: string example: Bearer authentication_method: type: string example: passwordless passwordless_type: type: string example: magic_link user: "$ref": "#/components/schemas/User" business: "$ref": "#/components/schemas/Business" '401': description: Invalid or expired token content: application/json: schema: "$ref": "#/components/schemas/Error" "/auth/passwordless/status": get: tags: - Passwordless Authentication summary: Get passwordless authentication status description: | Get information about recent passwordless authentication attempts and system configuration. responses: '200': description: Status retrieved successfully content: application/json: schema: type: object properties: passwordless_enabled: type: boolean description: Whether `POST /auth/passwordless/request` issues anything. Always false. example: false recent_tokens: type: array items: "$ref": "#/components/schemas/PasswordlessToken" supported_types: type: array description: Types `POST /auth/passwordless/request` issues. Always empty. items: type: string example: [] rate_limit_info: type: object properties: max_requests_per_5_minutes: type: integer example: 3 current_period_requests: type: integer example: 1 '401': "$ref": "#/components/responses/Unauthorized" "/auth/tokens": get: tags: - API Token Management summary: List personal API tokens description: | Retrieve a list of personal API tokens for the current user. Excludes session tokens and service account tokens. parameters: - "$ref": "#/components/parameters/Page" - "$ref": "#/components/parameters/PerPage" responses: '200': description: Tokens retrieved successfully content: application/json: schema: type: object properties: data: type: array items: "$ref": "#/components/schemas/PersonalApiToken" meta: type: object properties: total_tokens: type: integer description: Number of your personal API tokens, the same set `data` lists (no service accounts, no tokens the app mints at sign-in); revoked and expired tokens included active_tokens: type: integer description: How many of those personal tokens are active (not revoked, not expired) available_scopes: type: array items: type: string description: Available scopes for personal tokens pagination: "$ref": "#/components/schemas/PaginationMeta" '401': "$ref": "#/components/responses/Unauthorized" post: tags: - API Token Management summary: Create personal API token description: | Create a new personal API token with specified scopes and expiration. Requires current password for security verification, and a token with the `write:connections` scope (the app's own sign-in and the CLI carry it; a token you make carries it only when you grant it). requestBody: required: true content: application/json: schema: type: object required: - current_password properties: name: type: string description: Token name/description example: My Automation Token maxLength: 100 current_password: type: string description: Current password for verification scopes: type: array items: type: string description: Requested scopes (filtered to employee-safe scopes) example: - read:own_profile - read:own_shifts - write:own_attendance expires_at: type: string format: date-time description: Optional expiration date example: '2024-12-31T23:59:59Z' responses: '201': description: Token created successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: API token created successfully token: "$ref": "#/components/schemas/DetailedPersonalApiToken" warning: type: string example: Store this token securely. You will not be able to see it again. '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/CredentialsWriteForbidden" '422': description: Token limit exceeded or validation error content: application/json: schema: "$ref": "#/components/schemas/Error" "/auth/tokens/scopes": get: tags: - API Token Management summary: Get available token scopes description: | Retrieve list of available scopes for personal API tokens with descriptions and categories. responses: '200': description: Scopes retrieved successfully content: application/json: schema: type: object properties: available_scopes: type: array items: type: object properties: name: type: string example: read:own_profile description: type: string example: View your profile information category: type: string example: profile scope_categories: type: object additionalProperties: type: string example: profile: User profile and preferences shifts: Shift and schedule information '401': "$ref": "#/components/responses/Unauthorized" "/auth/tokens/{id}": get: tags: - API Token Management summary: Get token details description: Retrieve detailed information about a specific personal API token parameters: - name: id in: path required: true schema: type: integer description: Token ID responses: '200': description: Token details retrieved successfully content: application/json: schema: type: object properties: token: "$ref": "#/components/schemas/DetailedPersonalApiToken" '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" delete: tags: - API Token Management summary: Delete personal API token description: | Delete (revoke) a personal API token. Requires current password for security, and a token with the `write:connections` scope. parameters: - name: id in: path required: true schema: type: integer description: Token ID to delete requestBody: required: true content: application/json: schema: type: object required: - current_password properties: current_password: type: string description: Current password for verification responses: '200': description: Token deleted successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: API token revoked. deleted_token: "$ref": "#/components/schemas/PersonalApiToken" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/CredentialsWriteForbidden" '404': "$ref": "#/components/responses/NotFound" "/auth/tokens/{id}/rotate": patch: tags: - API Token Management summary: Rotate API token description: | Generate a new token value for an existing API token while preserving all other settings. Requires current password for security, and a token with the `write:connections` scope. parameters: - name: id in: path required: true schema: type: integer description: Token ID to rotate requestBody: required: true content: application/json: schema: type: object required: - current_password properties: current_password: type: string description: Current password for verification responses: '200': description: Token rotated successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: API token rotated successfully token: "$ref": "#/components/schemas/DetailedPersonalApiToken" old_token: type: object description: Information about the old token (without token value) warning: type: string example: Update your applications with the new token. The old token is no longer valid. '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/CredentialsWriteForbidden" '404': "$ref": "#/components/responses/NotFound" "/auth/tokens/{id}/usage": get: tags: - API Token Management summary: Get token usage statistics description: | Retrieve usage statistics and analytics for a personal API token. Note: Detailed usage tracking is being implemented. parameters: - name: id in: path required: true schema: type: integer description: Token ID responses: '200': description: Usage statistics retrieved successfully content: application/json: schema: type: object properties: usage: "$ref": "#/components/schemas/TokenUsage" note: type: string example: Usage tracking is being implemented and will provide detailed analytics soon. '401': "$ref": "#/components/responses/Unauthorized" '404': "$ref": "#/components/responses/NotFound" "/auth/impersonate": post: tags: - Impersonation summary: Create impersonation token description: | Create a short-lived impersonation token to act on behalf of a specific user. Requires a service account with `impersonate` or `admin` scope. Impersonation tokens allow service accounts to access user-specific endpoints (e.g., `/api/v1/users/me`, `/api/v1/leave_balances`) as if authenticated as that user. All access using impersonation tokens is automatically logged for audit purposes. security: - BearerAuth: [] - ServiceAccountAuth: [] requestBody: required: true content: application/json: schema: type: object required: - user_id properties: user_id: type: integer description: ID of the user to impersonate example: 123 responses: '201': description: Impersonation token created successfully. The token value is returned only in this response; it is stored as a digest and cannot be shown again. content: application/json: schema: type: object properties: token: type: string description: Impersonation token (use as a Bearer token in the Authorization header) example: a1b2c3d4e5f6... expires_at: type: string format: date-time description: Token expiration time example: '2024-01-15T14:30:00Z' impersonated_user: type: object properties: id: type: integer email: type: string name: type: string instructions: type: object properties: usage: type: string example: type: string '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': description: | The caller is not a service account (`service_account_required`), or the service account lacks the `impersonate` or `admin` scope (`insufficient_scope`). `impersonation_target_not_allowed` (only while impersonation target checks are enabled for the installation): the person may not be impersonated through this token. The `message` gives the reason: - "This person is a Super Admin in another organization, so only a Super Admin there can view the system as them." - "This person also belongs to another organization you don't administer, so only someone who administers every other organization they belong to can view the system as them." ("you" is the token's owner.) - "Only a token whose owner is a Super Admin in this organization can impersonate a Super Admin. Re-issue the token under a person who is a Super Admin here; a service account can't be one." While the checks are enabled they also run on every request of an open impersonation session, and a token whose person would now be refused gets `401`. While they are disabled, none of these refusals applies. content: application/json: schema: "$ref": "#/components/schemas/Error" example: error: code: insufficient_scope message: Service account requires 'impersonate' or 'admin' scope '404': description: User not found in current business content: application/json: schema: "$ref": "#/components/schemas/Error" example: error: code: user_not_found message: User not found in current business get: tags: - Impersonation summary: List active impersonation tokens description: | Returns the active impersonation tokens this service account created in the current business, newest first, at most 100. Requires a service account token with the `impersonate` or `admin` scope; any other caller, including an impersonation token, is refused with 403. security: - BearerAuth: [] - ServiceAccountAuth: [] responses: '200': description: Impersonation tokens retrieved successfully content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: integer description: Impersonation token record ID. The token value itself is never listed; it is returned once, when the token is created. impersonated_user: type: object properties: id: type: integer email: type: string name: type: string created_at: type: string format: date-time expires_at: type: string format: date-time description: Token expiration time revoked: type: boolean total_count: type: integer description: Number of tokens returned (at most 100). '401': "$ref": "#/components/responses/Unauthorized" '403': description: The caller is not a service account (`service_account_required`), or the service account lacks the `impersonate` or `admin` scope (`insufficient_scope`). content: application/json: schema: "$ref": "#/components/schemas/Error" "/auth/impersonate/{token}": delete: tags: - Impersonation summary: Revoke impersonation token description: | Revoke an impersonation token. Only the service account that created the token can revoke it. security: - BearerAuth: [] - ServiceAccountAuth: [] parameters: - name: token in: path required: true schema: type: string description: The impersonation token to revoke responses: '200': description: Token revoked successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: object properties: message: type: string example: Impersonation token revoked '401': "$ref": "#/components/responses/Unauthorized" '403': description: Access denied content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: Token not found or not owned by this service account content: application/json: schema: "$ref": "#/components/schemas/Error" "/home": get: tags: - Home summary: Get home screen data description: "Returns comprehensive home screen data including dashboard widgets, \nuser profile, business context, notifications, and quick stats.\n\nThis endpoint provides all data needed to render a complete mobile \nhome screen in a single API call.\n\n### Widget System\nThe dashboard includes configurable widgets based on:\n- User role (employee, manager, admin, super_admin)\n- Enabled business features\n- Active marketplace apps\n\n### Performance Metrics\nIncludes user performance data such as:\n- Weekly hours worked\n- Attendance rate and punctuality\n- Completed shifts count\n\n### Real-time Data\n- Current attendance status\n- Upcoming shifts\n- Unread notifications\n- Quick action shortcuts\n\n**Required Scopes:** `read:widgets` (#7183, owner rule 2026-10-06\n\"every api/v1 door asks a scope\") — the same aggregated, person-scoped\nhome payload as `GET /api/v1/widgets`, which asks it. A token without it\ngets `403 insufficient_permissions` (\"Required scope: read:widgets\").\nThe Inbox nodes inside (`waiting_on_you`, `notifications`, a manager's\n`quick_stats.pending_approvals`) still ask `read:notifications` on top,\nand are `null` without it. The sign-in tokens hold both; a browser\nsession is asked no scope.\n" parameters: - name: waiting_on_you_older in: query required: false schema: type: boolean description: 'Opt in to `waiting_on_you.older` — what is still waiting on the caller but was asked more than 90 days ago (the web Inbox''s collapsed "Older" group). Absent unless `1`/`true`; it costs a second pass over the approvals queues. ' - name: surface in: query required: false schema: type: string enum: - desktop description: "`desktop` answers one section of the desktop app's Home instead of the payload below; `section` says which.\n" - name: section in: query required: false schema: type: string enum: - manifest - attention - focus - schedule - today - you - review - week description: 'With `surface=desktop`. `attention` is Waiting on you with what each row asks (`read:notifications` on top). `focus` is the desktop''s "Do this first": up to three of the person''s ledger rows, most urgent first, leaving out what Waiting on you lists. Each row''s `can_snooze` and `can_dismiss` say what this token may do. `schedule` is the desktop Today''s schedule: today''s calendar in the person''s zone with each meeting''s join link, their answer and its AI Notepad note, the first invites waiting for an answer, and tomorrow''s first item once the day is clear, and for a manager `team_out`: who on their team is out today, with the reason only where the viewer may see it. It asks the Calendar''s `read:calendar_sync` and leaves out acknowledgment deadlines, which Waiting on you lists. `you` is the right column: the person''s time off (balances, a request waiting, the next approved leave and the leave types they may request), recognition received this week, today''s birthdays and work anniversaries in their department, and for a manager one report to recognize. `review` is To review: up to three items the person owns whose "Still accurate?" review is overdue or due soon, soonest first, as Content I own lists them, with `total` and each item''s `can_mark`. `week` is the weekly wrap: the signed-in person''s own week in at most five lines, counted by rules, from Friday 12:00 to Monday 12:00 in their zone. It answers `state` (`shown`, `outside_window`, `off_for_company`, `off_for_you`, or `unavailable` for an impersonated session, which is never answered any lines), `company_enabled` and `personal_enabled` (always present), `week_of` (the Monday of the week counted) and `shows_until` (the next Monday 12:00), both null unless shown, and `lines`: the first five, in this order, of `recognized_by` {count, names}, `messages` {sent, received, conversations, top: [{type: person|room, name}]}, `post_acknowledged` {room_name, acknowledged, of}, `clip_watched` {title, views, viewers}, `meetings` {meetings, noted, action_items}, `first_conversations` {count}, `mentions` {count} and `reactions` {received}, each sent only when it has something to say. The week counted is Monday 00:00 to Friday 12:00, worked out once and kept until the wrap closes; it counts facts, never scores or comparisons. There is no parameter to ask for anyone else''s week. ' - name: calendars in: query required: false schema: type: string enum: - connected description: 'With `section=schedule`: `connected` answers the connected Google / Outlook calendars alone. Those may be read live from the provider, so a client asks for them apart and the rest never waits on them. ' responses: '200': description: Home screen data retrieved successfully content: application/json: schema: type: object properties: user: allOf: - "$ref": "#/components/schemas/User" - type: object properties: language: type: string description: | The language content reaches the caller in — own setting, else their place's, else the company default. Never null (Knowledge Layer P4). example: en language_set: type: boolean description: Whether the caller chose a language themselves (`false` is "Not set"). onboarding_completed: type: boolean description: Whether user has completed onboarding onboarding_progress: type: number minimum: 0 maximum: 100 description: Onboarding completion percentage preferences: type: object description: User preferences and settings business: allOf: - "$ref": "#/components/schemas/Business" - type: object properties: settings: type: object properties: shifts_scheduling_enabled: type: boolean time_attendance_enabled: type: boolean leave_management_enabled: type: boolean timesheets_enabled: type: boolean skills_certifications_enabled: type: boolean enabled_marketplace_apps: type: array items: type: string description: List of enabled marketplace app slugs time_clock_kiosk_enabled: type: boolean description: 'Tenant runs a shared Time Clock Kiosk, so punching moved off personal devices onto the tablet at the site. Clients must stop offering Clock In / Clock Out and show the kiosk card from current_status.kiosk instead. ' business_hours: type: object additionalProperties: type: object properties: open: type: string format: time close: type: string format: time closed: type: boolean week_start_day: type: string enum: - sunday - monday - tuesday - wednesday - thursday - friday - saturday default: monday dashboard: type: object properties: widgets: type: array items: type: object properties: name: type: string description: Widget identifier title: type: string description: Display title description: type: string description: Widget description category: type: string enum: - platform - core_app - marketplace_app icon: type: string description: FontAwesome icon class size: type: string description: Bootstrap grid size class type: type: string description: Widget category type priority: type: integer description: Display priority (lower = higher priority) data: type: object description: | Widget-specific data content following the Simple Widget Specification. Contains both structured data and markdown content for flexible mobile rendering. **Core Structure**: - Original structured data (actions, shifts, notifications, etc.) - `markdown_summary`: Rich markdown content for mobile rendering - `display_hint`: Layout hint (grid, list, feed, card) **Platform Widgets**: - `quick_actions`: { actions: [{ title, path, icon, variant }], markdown_summary, display_hint: 'grid' } - `notifications`: { recent: [], unread_count: 0, markdown_summary, display_hint: 'feed' } - `user_profile_summary`: { greeting, weekly_hours, current_status, markdown_summary, display_hint: 'card' } **Core App Widgets**: - `upcoming_shifts`: { shifts: [], user_role, show_team_view, markdown_summary, display_hint: 'list' } - `quick_attendance`: { current_status: { status, shift: { id, date, start_time, end_time, location, duration, is_ad_hoc }, clocked_in_at, duration, can_clock_in }, today_hours, can_clock_in, markdown_summary, display_hint: 'card' } - `leave_requests`: { leave_requests: [{ id, start_date (YYYY-MM-DD), end_date (YYYY-MM-DD), formatted_dates, duration_days, status_badge: { class, text }, leave_type: { name, color }, reason, created_at, url }], leave_balance: [], quick_actions: [], user_role, show_manager_view, markdown_summary, display_hint: 'list' } **Marketplace App Widgets**: - `epms_*`: Performance management data with markdown_summary and display_hint - `training_connect_*`: Training data with markdown_summary and display_hint - `okr_progress`: OKR data with markdown_summary and display_hint This hybrid approach provides both structured data for custom rendering and markdown content for quick implementation. additionalProperties: true properties: markdown_summary: type: string description: Rich markdown content for mobile rendering. Contains formatted text with emojis, links, and styling cues. example: "## Quick Actions\n\n\U0001F535 **[Clock In](/attendance/clock_in)**\n\U0001F4C5 **[My Schedule](/shifts/my_shifts)**\n" display_hint: type: string enum: - grid - list - feed - card description: | Layout hint for mobile apps: - grid: 2-3 column layout for actions/buttons - list: Single column with dividers for items - feed: Card-based with timestamps for activity - card: Full-width summary display example: actions: - title: Clock In path: "/attendance/clock_in" icon: fas fa-play variant: primary - title: My Schedule path: "/shifts/my_shifts" icon: fas fa-calendar variant: outline-info last_updated: type: string format: date-time refresh_interval: type: integer description: Recommended refresh interval in seconds data_schema: type: object description: | JSON Schema describing the expected structure of the 'data' field. Helps mobile developers understand widget data format and handle new widgets gracefully. additionalProperties: true version: type: string description: | Widget version for mobile app compatibility. Increment when widget data structure changes significantly. example: '1.2' widget_count: type: integer description: Total number of active widgets performance_metrics: type: object properties: current_week: type: object properties: hours_worked: type: number format: float shifts_completed: type: integer on_time_rate: type: number format: float minimum: 0 maximum: 100 attendance_rate: type: number format: float minimum: 0 maximum: 100 current_month: type: object properties: total_shifts: type: integer hours_worked: type: number format: float performance_score: type: number format: float minimum: 0 maximum: 100 role_context: type: object properties: current_role: type: string enum: - employee - manager - admin - super_admin permissions: type: array items: type: string description: User's permissions in current business available_actions: type: array items: type: object properties: name: type: string label: type: string icon: type: string attendance_policy: type: object nullable: true description: 'The tenant''s clock-in policy, resolved for the calling user, so a client can render the clock-in gate and know which verifications to gather without re-implementing the rules. `null` when Time & Attendance is disabled for the business or the business has no security setting yet. `settings` mirrors every punch-behaviour field on /admin/attendance_security/settings, using the same names. Kiosk PIN derivation (`default_pin_rule`, `default_pin_custom_value`) is deliberately never returned; the caller''s own PIN-free kiosk credentials ship in `current_status.kiosk` instead. ' properties: punches_paused: type: boolean description: 'True while the tenant''s maintenance refuses punches for this caller (a read-only freeze, or a window that blocks every worker door): draw Clock In / Clock Out, breaks and undo disabled instead of offering a punch the server answers with a 503. ' paused_until: type: string format: date-time nullable: true description: When the pause is expected to end (ISO 8601); null when it lifts only when an administrator lifts it, or when nothing is paused. clock_in_gate: type: object properties: active: type: boolean description: 'The decision, and the only field a client should branch on. Already folds in scope, admin exemption, approved leave and "already clocked in". Comes from the same resolver the web gate uses, so the two cannot drift. ' mode: type: string nullable: true enum: - block - banner description: 'How to present the gate — `block` redirects until clocked in, `banner` reminds without blocking. `null` when the gate is disabled for the tenant. ' enabled: type: boolean description: 'Raw tenant setting (is the gate switched on at all). Informational — re-deriving the gate from this will drift from `active`. ' scope: type: string enum: - punch_eligible - all_users description: Raw tenant setting for who the gate applies to. Informational. settings: type: object description: Straight projection of the tenant's attendance security settings. properties: allow_remote_clock_in: type: boolean description: Offer a "Working remotely" option in the location picker. allow_offsite_clock_in: type: boolean description: Offer an "Off-site / traveling" option with an optional note. require_shift_for_clock_in: type: boolean description: 'A punch is only accepted against a scheduled shift. When false, an ad-hoc shift is created for an unscheduled clock-in. ' require_location_verification: type: boolean description: 'Master switch for geographic verification. Each location must also enable geofencing for enforcement to take effect. ' require_device_verification: type: boolean require_photo_verification: type: boolean description: Employee must capture a photo when clocking in or out. enforce_ip_validation_for_clock_actions: type: boolean description: 'Master switch for the IP check. When false, no IP validation happens at all regardless of `ip_validation_mode`. ' ip_validation_mode: type: string enum: - passive - warning - strict description: 'Only meaningful when `enforce_ip_validation_for_clock_actions` is true. `passive` records only, `warning` flags for review, `strict` refuses the punch from an unapproved IP. ' enforce_time_window_restrictions: type: boolean description: 'Apply the three buffers below. Note the window check is skipped entirely for ad-hoc shifts even when this is true, so do not present a window on a punch against one. ' early_clock_in_buffer_minutes: type: integer description: 'Minutes before scheduled shift start that clock-in is allowed. `0` requires the exact start time. ' late_clock_in_buffer_minutes: type: integer description: 'Minutes after shift start before a clock-in is flagged as outside the window. `0` requires the exact start time. ' late_clock_out_buffer_minutes: type: integer description: 'Minutes after shift end before a clock-out is flagged. `0` disables the check — late clock-outs are never flagged — rather than meaning zero tolerance, which is the opposite of how `0` reads on the two clock-in buffers above. Early clock-out is never restricted at all. ' enable_auto_clock_out: type: boolean description: 'The server closes forgotten punches. Surfaced so a client can warn the employee rather than have an auto clock-out look like a lost shift. ' auto_clock_out_max_hours: type: integer description: Hours after clock-in at which the punch is closed automatically. auto_clock_out_after_shift_end_minutes: type: integer description: For scheduled shifts, minutes after shift end before auto clock-out. enable_clock_out_reminders: type: boolean description: 'Send a reminder before the shift ends. Independent of `enable_auto_clock_out` — the sweep selects the union of the two flags, so a tenant may receive reminders without the server ever auto-closing a punch. Do not present this as a sub-setting of auto clock-out. ' effective_clock_out_reminder_minutes: type: integer minimum: 5 description: 'Minutes before scheduled shift end that the reminder is sent. This is the stored `clock_out_reminder_minutes_before` clamped to the reminder sweep''s cron floor, not the raw column — a row holding a lower value (or none) still reminds at the floor, so this is the only number safe to show an employee. ' broadcast_alerts: type: object nullable: true description: 'Unread/response badge counts for the Broadcast & Alerts app. `null` when the app is not enabled for the business. Each `count` matches the `all` value the corresponding list API returns in `meta.segment_counts`, so the home badge can''t drift from the list. A `count` may be `null` if its computation fails (the node is still returned). ' properties: broadcast: type: object properties: count: type: integer nullable: true description: Received broadcasts the user has not read alert: type: object properties: count: type: integer nullable: true description: Alert responses (acknowledge / safety check-in) the user owes items: type: array maxItems: 10 description: 'The response-pending alerts the count covers — ack-required alerts the user has not acknowledged, or safety-check-in alerts the user has not responded to — newest published first, capped at 10 (a preview; the full total is in `count`). ' items: type: object properties: id: type: integer title: type: string your_tasks: type: object nullable: true description: 'The Home briefing''s "Your tasks": what the caller owes across apps — tasks, courses, onboarding items, documents to sign, inspections, shift offers, Frontline work — ranked overdue first. Null unless an administrator turned the Home briefing on. Must-reads and approvals are in `waiting_on_you`. ' properties: items: type: array description: The first five rows. items: type: object description: One item of the worker's day, projected from its owning app. Acted on in that app — this surface only ranks and links. properties: source: type: string description: Which app this row came from. enum: - frontline - inspections - must_reads - tasks - training - shift_offers - approvals - onboarding - signatures example: frontline key: type: string description: Stable cross-source id, for de-dup across pages. example: frontline-1187 title: type: string example: Close-out safety walk subtitle: type: string nullable: true description: Location or lane context. example: Store 412 priority: type: string enum: - critical - important - normal example: normal overdue: type: boolean example: false due_at: type: string format: date-time nullable: true url: type: string nullable: true description: Where to act on the row, in the app that owns it. Null when that app resolved no route (render no link rather than a broken one). example: "/apps/frontline-execution/my-day" mobile_url: type: string nullable: true description: The row's phone page, where it is not simply the phone form of `url` (an onboarding form). Null otherwise. action_label: type: string description: The verb for the row's action. example: Open rank_reason: type: string nullable: true description: Why the row is ranked where it is. example: Due 5:00 PM. blocked: type: boolean description: Whether the worker has flagged this as "I can't do this". Only a `frontline` row can be flagged; every other source is always false. example: true blocked_reason: type: string nullable: true description: What is blocking it — the reason the worker picked when flagging. Null when not flagged. enum: - no_stock - missing_fixture_or_supplies - equipment_down - not_enough_time - unclear_instructions - other example: missing_fixture_or_supplies blocked_reason_label: type: string nullable: true description: Human-readable label for `blocked_reason`. Null when not flagged. example: Missing fixture or supplies blocked_note: type: string nullable: true maxLength: 500 description: The note the worker left for their manager when flagging it ("Anything your manager should know"). Optional when flagging, so it can be null on a flagged row; always null on an unflagged one. example: Promo signage never arrived in the delivery blocked_at: type: string format: date-time nullable: true description: When it was flagged. Null when not flagged. total: type: integer description: How many rows the whole list holds. degraded_sources: type: array description: Apps whose rows could not be loaded, so the list is incomplete. items: type: string trip: type: object nullable: true description: 'The Home briefing''s "Your assignment": the dated work assignment (a posting, a rotation, a trip) the caller is on or about to start — the one under way, else the next. Null when the caller has none, and unless an administrator turned the Home briefing on. ' properties: id: type: integer location: type: object properties: id: type: integer nullable: true name: type: string starts_on: type: string format: date ends_on: type: string format: date nullable: true description: Null while the assignment has no end date. status: type: string enum: - scheduled - active countdown: type: string nullable: true description: '"Starts in 9 days", "Starts tomorrow", "Day 3 of 28".' report_to: type: string nullable: true description: Full name of the person to report to on arrival. report_at: type: string format: date-time nullable: true description: When to report, in the time zone of the location. travel: type: array description: The legs of the journey there, in order. items: type: object properties: mode: type: string enum: - flight - helicopter - ferry - train - bus - car - other label: type: string description: '"Flight · Aberdeen → Bergen".' detail: type: string nullable: true description: The departure time as the ticket shows it, and the reference. before_you_go_count: type: integer description: Open pre-start items on the pre-arrival plan opened for this assignment; 0 with no plan. waiting_on_you: type: object nullable: true description: 'The ONE "Waiting on you" (Knowledge Layer E2) — the same list the Home briefing, the rail''s per-app counts and the Inbox''s ?view=waiting (and /m/inbox?view=waiting) show, over what was asked in the last 90 days (older asks: `older`). Two halves: what the caller DECIDES (`to_decide` — every approvals queue whose decision is theirs) and what they were asked to read and confirm and have not (`to_acknowledge_count`, `items`, `counts_by_kind` — must-read posts, broadcasts, alerts, Sites pages, policies and SOPs, each from that app''s own pending list, never from notification rows, so an ask in a muted category is still here). Not summed into `quick_stats.unread_notifications`. `null` if the computation fails, and for a token without `read:notifications` — as are `notifications` and, for a manager, `quick_stats.pending_approvals` (the Inbox is read only with that scope). ' properties: count: type: integer description: 'Everything asked in the last 90 days, uncapped — `to_decide.count` plus `to_acknowledge_count`. ' to_decide: type: object description: '"To decide" — what the caller decides (the approvals registry: people''s requests, AI suggestions, …). The same number as `quick_stats.pending_approvals`. ' properties: count: type: integer description: Everything to decide asked in the last 90 days, uncapped counts_by_source: type: object description: The count split by approvals source (e.g. `leave_requests`) additionalProperties: type: integer items: type: array maxItems: 10 description: 'A preview, most urgent first (overdue, then soon, then oldest request), capped at 10. Decided where `url` links. ' items: "$ref": "#/components/schemas/WaitingOnYouDecideRow" to_acknowledge_count: type: integer description: '"To acknowledge" — everything the caller was asked in the last 90 days to confirm and has not, uncapped (`items` / `counts_by_kind`). ' counts_by_kind: type: object description: The "To acknowledge" count split by kind (kinds with nothing waiting are omitted) additionalProperties: type: integer items: type: array maxItems: 10 description: '"To acknowledge" preview, most urgent first (overdue, then soonest due, then newest ask), capped at 10. ' items: "$ref": "#/components/schemas/WaitingOnYouAcknowledgeItem" degraded: type: array description: 'What failed to load just now — acknowledgement kinds and approvals sources — so the list may be missing them ' items: type: string older: type: object description: 'Only with `?waiting_on_you_older=1` (the key is absent otherwise). Still open but asked more than 90 days ago, so in no count above and no badge — the web Inbox''s collapsed "Older" group. ' properties: count: type: integer description: Everything older, uncapped (`to_decide_count` + `to_acknowledge_count`) to_decide_count: type: integer to_acknowledge_count: type: integer to_decide: type: array maxItems: 20 description: Decided with `POST /home/waiting_on_you/decide`, as `to_decide.items` items: "$ref": "#/components/schemas/WaitingOnYouDecideRow" to_acknowledge: type: array maxItems: 20 description: Same item shape as `waiting_on_you.items` items: "$ref": "#/components/schemas/WaitingOnYouAcknowledgeItem" degraded: type: array items: type: string forms: type: object nullable: true description: 'Forms pending-approval badge. `null` unless the Forms app is enabled for the business AND the caller may approve/reject submissions (admin / manager / Forms App Admin) — the same gate as GET /api/v1/forms/approvals. Returned `null` (never omitted erroneously) if the count computation fails, so the home payload is never dropped. ' properties: pending_approval_count: type: integer description: 'Submissions awaiting the caller''s review. Role-aware, matching the size of GET /api/v1/forms/approvals so the badge can''t drift from that list: admins and Forms App Admins count the business-wide pending_review set (submitted + under_review); a manager counts only the under_review submissions from their own direct reports. ' notifications: type: object properties: unread_count: type: integer description: Number of unread notifications total_count: type: integer description: Total notifications for user recent: type: array items: type: object properties: id: type: integer title: type: string message: type: string type: type: string priority: type: string enum: - low - normal - high - urgent default: normal created_at: type: string format: date-time read_at: type: string format: date-time nullable: true action_url: type: string nullable: true link_withheld_app: type: string nullable: true description: 'When `action_url` is null because the app it leads into will not let this reader in, that app''s name; null otherwise. ' quick_stats: type: object properties: today_shifts: type: integer description: Number of shifts today week_hours: type: number format: float description: Hours worked this week unread_notifications: type: integer description: Unread notification count pending_approvals: type: integer description: 'What the caller decides — the approvals registry''s count, the same number as `waiting_on_you.to_decide.count` and the web home and approvals page (managers/admins only). Was a business-wide count of pending leave requests and attendance records flagged for review, whoever could act. ' team_size: type: integer description: Team size (managers/admins only) today_employee_count: type: integer description: Employees scheduled today (managers/admins only) _meta: allOf: - "$ref": "#/components/schemas/HttpEnhancementMeta" - type: object properties: refresh_interval: type: integer description: Recommended refresh interval in seconds example: 300 server_time: type: string format: date-time description: Current server time mobile_optimized: type: boolean example: true cache_key: type: string description: Cache key for client-side caching examples: employee_home: summary: Employee home screen value: user: id: 123 email: john.doe@company.com first_name: John last_name: Doe full_name: John Doe role: employee active: true avatar_url: phone: "+1234567890" onboarding_completed: true onboarding_progress: 100 preferences: {} business: id: 456 name: Example Company subdomain: example timezone: America/New_York logo_url: branding: primary_button_color: "#2e63b3" secondary_button_color: "#6c757d" status_success_color: "#198754" status_error_color: "#dc3545" status_warning_color: "#ffc107" status_info_color: "#0dcaf0" mobile_header_background: "#2e63b3" mobile_header_text: "#FFFFFF" mobile_footer_background: "#FFFFFF" mobile_footer_icon_active: "#2e63b3" mobile_footer_icon_inactive: "#6c757d" settings: shifts_scheduling_enabled: true time_attendance_enabled: true leave_management_enabled: true enabled_marketplace_apps: - epms - training_connect week_start_day: monday dashboard: widgets: - name: quick_actions title: Quick Actions category: platform icon: fas fa-bolt size: col-12 priority: 1 data: actions: - title: Clock In path: "/attendance/clock_in" icon: fas fa-play variant: primary - title: My Schedule path: "/shifts/my_shifts" icon: fas fa-calendar variant: outline-info data_schema: type: object properties: actions: type: array items: type: object properties: title: type: string path: type: string icon: type: string variant: type: string version: '1.2' refresh_interval: 300 - name: upcoming_shifts title: Upcoming Shifts category: core_app icon: fas fa-calendar size: col-md-6 priority: 3 data: shifts: - id: 789 title: Morning Shift start_time: '2024-01-15T08:00:00Z' end_time: '2024-01-15T16:00:00Z' location: Main Office total_count: 5 refresh_interval: 300 - name: quick_attendance title: Time Clock category: core_app icon: fas fa-clock size: col-md-6 priority: 2 data: current_status: status: scheduled shift: id: 789 date: '2024-01-15' start_time: '08:00 AM' end_time: 04:00 PM location: Main Office duration: 8h 0m is_ad_hoc: false can_clock_in: true today_hours: 0.0 markdown_summary: 'Next Shift: Today, 08:00 AM - 04:00 PM at Main Office' display_hint: card refresh_interval: 60 widget_count: 3 performance_metrics: current_week: hours_worked: 32.5 shifts_completed: 4 on_time_rate: 95.2 attendance_rate: 98.1 current_month: total_shifts: 18 hours_worked: 142.5 performance_score: 96.5 role_context: current_role: employee permissions: - read_dashboard - view_profile available_actions: - name: view_profile label: View Profile icon: fas fa-user - name: clock_in_out label: Clock In/Out icon: fas fa-clock notifications: unread_count: 3 total_count: 25 recent: - id: 101 title: Schedule Update message: Your shift on Jan 15 has been updated type: shift_update priority: normal created_at: '2024-01-14T10:30:00Z' read_at: action_url: "/shifts/789" quick_stats: today_shifts: 1 week_hours: 32.5 unread_notifications: 3 _meta: api_version: v1 generated_at: '2024-01-15T12:00:00Z' refresh_interval: 300 server_time: '2024-01-15T12:00:00Z' mobile_optimized: true cache_key: home_123_456_1705320000 '401': "$ref": "#/components/responses/Unauthorized" '403': description: The token lacks `read:widgets` (`insufficient_permissions`). content: application/json: schema: "$ref": "#/components/schemas/Error" '500': description: Internal server error content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: home_data_error message: type: string example: Failed to load home screen data "/home/waiting_on_you/decide": post: tags: - Home summary: Decide a "To decide" row of Waiting on you description: | Approve or decline one `waiting_on_you.to_decide.items` row from `GET /api/v1/home` (Knowledge Layer C3 — approve anywhere). `source` and `id` are the row's own. The approvals registry's one decide path — the same one the web and phone "Waiting on you", the approvals page and the Teams / Slack cards take: the queue's door re-checked now, the row in the caller's own queue right now, a reason where the queue asks one of a decline, then the owning app's own action, run as the caller. "Not waiting" is one answer for a row already decided and a row that was never the caller's, so it reveals nothing about someone else's. A token needs the `write:approvals` scope (the native app's sign-in tokens carry it); without it the row's `can_approve` / `can_decline` read false and this answers 403 `insufficient_permissions`. Delete-level (owner decisions 2026-10-04, #6659 and #6721): EVERY decline — a decision that ends someone else's request — also requires the delete scope of the area the request belongs to: declining a leave request `destructive:leave_management`, a timesheet `destructive:timekeeping`, an expense report `destructive:mango_spend`, a form submission `destructive:forms`, a goal or review `destructive:epms`, a contract `destructive:contracts`, an offer `destructive:offer_manager`, and so on (an AI suggestion is the one exception: declining it ends nobody's request). Approving a nomination asks `destructive:recognition` too. Without it the row's `can_approve` / `can_decline` read false for that verdict and this answers 403 `insufficient_permissions` naming the scope. operationId: decideWaitingOnYou requestBody: required: true content: application/json: schema: type: object required: - source - id - verdict properties: source: type: string description: The row's approvals source key (`to_decide.items[].source`). example: ai_suggestions id: type: integer description: The row's id (`to_decide.items[].id`). verdict: type: string enum: - approve - reject surface: type: string enum: - inbox - approvals_page - home - today - phone - email - teams - slack - ask_ai - chat description: 'The screen the person decides on, when the client knows it. It is what a Chat card says the decision came from; any other value is ignored. ' reason: type: string description: Required to decline a row whose `decline_needs_reason` is true. responses: '200': description: Decided content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string description: The owning app's own sentence. waiting_on_you: type: object nullable: true description: 'The counts after the decision, so the Home badge moves with it; `null` for a token without `read:notifications`. ' properties: count: type: integer to_decide_count: type: integer '401': "$ref": "#/components/responses/Unauthorized" '403': description: "`insufficient_permissions` — the token has no `write:approvals` scope, or no delete scope for a delete-level verdict (the message names it); `queue_unavailable` — no such queue, or its app is off for this workspace.\n" '409': description: "`not_waiting` — already decided, or not the caller's to decide." '422': description: "`reason_required` (decline with no reason where the queue asks one), `invalid_verdict`, or `decision_refused` (the owning app's own refusal, in `error.message`).\n" "/home/focus/{id}/snooze": post: tags: - Home summary: Snooze a "Do this first" row description: | Parks one row of `GET /api/v1/home?surface=desktop§ion=focus` in the caller's own feed, and it comes back when the time is up. The same writer as AI Home's Snooze: it needs the row to be in the caller's feed, not authority over it, and it changes nothing for anyone else. A token needs the `write:approvals` scope; without it the row's `can_snooze` reads false and this answers 403 `insufficient_permissions`. operationId: snoozeHomeFocusRow parameters: - name: id in: path required: true schema: type: integer requestBody: required: false content: application/json: schema: type: object properties: hours: type: integer minimum: 1 maximum: 168 default: 4 description: How long, in hours. Kept within 1 hour and 7 days. responses: '200': description: Snoozed. content: application/json: schema: type: object properties: success: type: boolean '401': "$ref": "#/components/responses/Unauthorized" '403': description: "`insufficient_permissions` — the token has no `write:approvals` scope." '404': description: "`not_found` — the row is not in the caller's feed." "/home/focus/{id}/dismiss": post: tags: - Home summary: Dismiss a "Do this first" row description: | Closes one row of `GET /api/v1/home?surface=desktop§ion=focus`, on AI Home's Dismiss rules: never a report's own obligation, and only for someone who decides that row. A row with a decision in it is answered from "To decide" instead, with `POST /home/waiting_on_you/decide`. A token needs the `write:approvals` scope; without it the row's `can_dismiss` reads false and this answers 403 `insufficient_permissions`. operationId: dismissHomeFocusRow parameters: - name: id in: path required: true schema: type: integer requestBody: required: false content: application/json: schema: type: object properties: reason: type: string description: Why, kept on the row's record. responses: '200': description: Dismissed. content: application/json: schema: type: object properties: success: type: boolean '401': "$ref": "#/components/responses/Unauthorized" '403': description: "`insufficient_permissions` — the token has no `write:approvals` scope; `forbidden` — the row is not the caller's to close.\n" '404': description: "`not_found` — the row is not in the caller's feed." '422': description: "`decide_instead` — the row has a decision in it; or `unprocessable_entity` — it was already decided, or its app needs a reason given through Decline.\n" "/home/review/{subject_type}/{id}/still_accurate": post: tags: - Home summary: Mark an item from To review still accurate description: | Marks one item of `GET /api/v1/home?surface=desktop§ion=review` as still accurate, as Content I own's Still accurate does: its review clock restarts without an edit, and its stale finding resolves. Only the person the item is listed for (its owner, a member of its owning team, or its author while nobody is named) who can open it may do it. A token needs the `write:widgets` scope; without it this answers 403 `insufficient_permissions`. operationId: markHomeReviewStillAccurate parameters: - name: subject_type in: path required: true schema: type: string description: The item's `subject_type` from the review row, such as `Sop`. - name: id in: path required: true schema: type: integer responses: '200': description: Marked. content: application/json: schema: type: object properties: success: type: boolean next_review_at: type: string format: date-time nullable: true description: When its review falls due again; null while governance is off for its app. '401': "$ref": "#/components/responses/Unauthorized" '403': description: "`insufficient_permissions` — the token has no `write:widgets` scope; `forbidden` — the item is not listed for the caller.\n" '404': description: "`not_found` — no item of a type this can mark has that id." "/home/week/preference": patch: tags: - Home summary: Turn the weekly wrap on Today off or on for yourself description: | The signed-in person's own switch for the weekly wrap (`GET /api/v1/home?surface=desktop§ion=week`), in this company. Off, the wrap answers `off_for_you` and is never worked out for them. There is no parameter for anyone else, and an impersonated session may not change it. A token needs the `write:widgets` scope; without it this answers 403 `insufficient_permissions`. operationId: updateHomeWeekPreference requestBody: required: true content: application/json: schema: type: object required: - enabled properties: enabled: type: boolean description: false turns the wrap off for the caller; true turns it back on. responses: '200': description: Saved. content: application/json: schema: type: object properties: success: type: boolean personal_enabled: type: boolean '401': "$ref": "#/components/responses/Unauthorized" '403': description: "`insufficient_permissions` — the token has no `write:widgets` scope; `impersonated` — the session is acting as someone else.\n" '422': description: "`invalid_parameter` — `enabled` is not true or false." "/users/me": get: tags: - Users summary: Get current user profile (Enhanced) description: | Returns the authenticated user's profile and business information, with optional `include` fields for enhanced mobile and web app experiences. ## Enhanced Features Use the `include` query parameter to request additional data: - `complete_profile` - Full profile with professional and compensation data - `dashboard_summary` - Dashboard stats and quick actions - `intelligence_insights` - AI-powered insights and recommendations - `preferences_detailed` - Detailed preferences with metadata ## Examples ``` GET /api/v1/users/me?include=complete_profile,dashboard_summary GET /api/v1/users/me?include=intelligence_insights ``` parameters: - name: include in: query description: | Comma-separated list of additional data to include in the response. Available options: complete_profile, dashboard_summary, intelligence_insights, preferences_detailed required: false schema: type: string example: complete_profile,dashboard_summary responses: '200': description: User profile retrieved successfully content: application/json: schema: type: object properties: user: "$ref": "#/components/schemas/CurrentUser" business: "$ref": "#/components/schemas/Business" _meta: "$ref": "#/components/schemas/HttpEnhancementMeta" '401': "$ref": "#/components/responses/Unauthorized" "/users/me/preferences": patch: tags: - Users summary: Update user preferences (Enhanced) description: | Update the authenticated user's preferences with support for category-based updates and smart defaults integration. ## Enhanced Features - Category-specific updates using `?category=notifications` - Smart defaults with `?include_smart_defaults=true` - Atomic updates to prevent conflicts ## Examples ``` PATCH /api/v1/users/me/preferences?category=notifications PATCH /api/v1/users/me/preferences?include_smart_defaults=true ``` parameters: - name: category in: query description: | Update only a specific preference category. Available categories: notifications, availability, communication, privacy required: false schema: type: string enum: - notifications - availability - communication - privacy example: notifications - name: include_smart_defaults in: query description: Include AI-powered smart defaults in the response required: false schema: type: boolean example: true requestBody: required: true content: application/json: schema: type: object required: - preferences properties: preferences: type: object description: User preferences to update example: theme: dark notifications_enabled: true language: en responses: '200': description: Preferences updated successfully content: application/json: schema: type: object properties: user: type: object properties: id: type: integer preferences: type: object '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '422': "$ref": "#/components/responses/ValidationError" "/users/{id}": get: tags: - Users security: - BearerAuth: [] summary: Get a user's HRIS detail (by employee UID) description: | The HRIS detail of one person in the caller's business, looked up by `mango_employee_id` (the `uid` the list returns — e.g. `E1234567`), not the numeric id (that is `GET /users/{id}/profile`). Requires `read:people_directory` (`read:users` implies it). `legal_entity` (Knowledge Layer X5) is the person's employing legal entity: their own override, else the nearest one set on their location or a place above it; null when neither names one. `language` is their stored SETTING (null = "Not set", they follow their place) — a profile field, unlike `/users/me`, whose `language` is the resolved one. parameters: - name: id in: path required: true description: The person's employee UID (`mango_employee_id`). schema: type: string example: E1234567 responses: '200': description: User detail content: application/json: schema: type: object properties: user: "$ref": "#/components/schemas/UserDetail" '401': "$ref": "#/components/responses/Unauthorized" '403': description: The token lacks `read:people_directory`. '404': description: "`user_not_found` — no one in this business has that UID." "/users/by_email/{email}": get: tags: - Users security: - BearerAuth: [] summary: Get a user's HRIS detail (by email) description: | The same payload as `GET /users/{id}`, looked up by email address (case-insensitive) among the caller's business's members. Requires `read:people_directory`. parameters: - name: email in: path required: true schema: type: string format: email responses: '200': description: User detail content: application/json: schema: type: object properties: user: "$ref": "#/components/schemas/UserDetail" '401': "$ref": "#/components/responses/Unauthorized" '403': description: The token lacks `read:people_directory`. '404': description: "`user_not_found`." "/users/{id}/profile": get: tags: - Users security: - BearerAuth: [] summary: Mobile profile card for a user (numeric id lookup) description: | Returns a mobile-friendly profile card for the user with the given numeric `User#id` — the value mobile clients receive from feed payloads, comment author blocks, and mention search results. Distinct from `GET /api/v1/users/{id}` which is the HRIS endpoint keyed on `mango_employee_id`. Tenant-scoped: only users with an active `UserBusiness` row in the caller's business are resolvable; cross-tenant or inactive ids return 404. Direct reports are filtered to the caller's business + active memberships, so the list never leaks ex-employees or users from other tenants the manager may belong to. `profile_picture.*` URLs and `mobile_url` are absolute so JSON clients can render / open them directly without resolving against a base URL. parameters: - name: id in: path required: true schema: type: integer minimum: 1 description: Numeric User#id. responses: '200': description: Mobile profile card content: application/json: schema: type: object required: - user properties: user: type: object required: - id - name - email - profile_picture - direct_reports - mobile_url properties: id: type: integer name: type: string nullable: true email: type: string format: email nullable: true contact: type: string nullable: true description: Primary phone number (User#phone). employee_id: type: string nullable: true description: HRIS-facing mango_employee_id (e.g. E1234567). job_title: type: string nullable: true employment_type: type: string nullable: true description: 'One of EMPLOYEE_TYPES: Full-Time, Part-Time, Seasonal/Temp, Hourly, Salaried, Contractor, Other.' hire_date: type: string format: date nullable: true profile_picture: type: object properties: thumbnail_url: type: string format: uri nullable: true description: 40x40 variant; absolute URL. full_url: type: string format: uri nullable: true description: 200x200 variant; absolute URL. primary_location: type: object nullable: true properties: id: type: integer name: type: string address: type: string nullable: true direct_reports: type: array description: Direct reports filtered to the caller's business + active UserBusiness. items: type: object properties: id: type: integer name: type: string nullable: true email: type: string format: email nullable: true profile_picture: type: object properties: thumbnail_url: type: string format: uri nullable: true full_url: type: string format: uri nullable: true custom_fields: type: array description: The organization's own profile fields on this person that the caller may see there, as `GET /users/{id}` lists them. items: "$ref": "#/components/schemas/ProfileCustomField" can_message: type: boolean description: 'Whether the caller may start a message with this person, as the web profile''s Message button decides: Messages is theirs to start, no information barrier stands between the two, and the token may write messages (`write:messages`). False on your own profile.' message_restriction: type: string nullable: true description: Why the caller may not message this person when an information barrier is the reason, in the caller's language (the sentence the web profile shows where the Message button would be). The barrier covers Chat too, so a client hides its Message and Chat buttons and shows this instead; it is set whenever Messages or Chat is open to the caller, so a company with Chat and without Messages still gets it. Null otherwise. mobile_url: type: string format: uri description: | Absolute deep link to the user's mobile profile, following the `/m/...` convention used by `mobile_app_url(slug)`. Clients can hand this to the WebView or in-app router. '400': description: id is not numeric '401': "$ref": "#/components/responses/Unauthorized" '404': description: User not found or not in the caller business "/profile": get: tags: - User Profile Management summary: Get complete user profile (redirects to /users/me) description: "Redirects to the enhanced /users/me endpoint. This endpoint is provided \nfor consistency but clients should use /users/me directly with include parameters.\nThe caller's answers to the organization's own profile fields are in\n`user.custom_fields` there.\n" responses: '302': description: Redirect to /users/me '401': "$ref": "#/components/responses/Unauthorized" "/profile/actions": post: tags: - User Profile Management summary: Execute profile actions description: "Execute various profile-related actions in a single endpoint. This allows\nfor specific operations like avatar updates, skill verification requests,\ncareer goal setting, and more.\n\n**Note:** Use `action_type` parameter (preferred) or `action` parameter for the action. \nUsing `action_type` is recommended as `action` is a reserved Rails parameter.\n" requestBody: required: true content: application/json: schema: type: object required: - action_type properties: action_type: type: string enum: - update_avatar - request_skill_verification - set_career_goal - update_emergency_contact - set_emergency_contact_detention_notice - request_manager_change - update_communication_preferences - request_personnel_file_copy description: The action to perform (preferred parameter) example: update_avatar action: type: string enum: - update_avatar - request_skill_verification - set_career_goal - update_emergency_contact - set_emergency_contact_detention_notice - request_manager_change - update_communication_preferences - request_personnel_file_copy description: The action to perform (legacy, use action_type instead) deprecated: true example: update_avatar data: type: object description: Action-specific data example: avatar: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD... examples: update_avatar: summary: Update profile avatar value: action_type: update_avatar data: avatar: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD... request_skill_verification: summary: Request skill verification value: action_type: request_skill_verification data: skill_id: 123 set_career_goal: summary: Set career goal value: action_type: set_career_goal data: goal: Complete React Certification target_date: '2024-06-01' update_emergency_contact: summary: Update emergency contact value: action_type: update_emergency_contact data: contact_info: name: Jane Doe phone: "+1234567890" relationship: Spouse set_emergency_contact_detention_notice: summary: Say whether your emergency contact is told if you are arrested or detained at work (California SB 294) value: action_type: set_emergency_contact_detention_notice data: answer: 'yes' request_personnel_file_copy: summary: Ask HR for a free copy of your own personnel file (no data; never under View-as — 403 impersonation_not_allowed; 409 already_requested while one is waiting, details.request is that one; on success data.request is { id, status, requested_at, due_on }) value: action_type: request_personnel_file_copy request_manager_change: summary: Ask for a change of manager description: | Files a People profile change request for an approver. `reason` is required. `effective_date` (`YYYY-MM-DD`, today or later) is optional, unless the People approval workflow the change meets has "Require Effective Date" on: then a filing without one answers 422 `effective_date_required`. A date that is not a `YYYY-MM-DD` string answers 400 `invalid_effective_date`, and a past date 422 `manager_request_invalid`. The filed request is returned with its `effective_date`. value: action_type: request_manager_change data: manager_id: 42 reason: I moved to the evening team effective_date: '2026-11-02' responses: '200': description: Action executed successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Avatar updated successfully data: type: object description: Action-specific response data '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': description: "`self_service_disabled` (a profile edit while employee self-service is off), or `impersonation_not_allowed` (request_personnel_file_copy under View-as).\n" '409': description: "`already_requested` (request_personnel_file_copy while one is waiting; `error.details.request` is that one: { id, status, requested_at, due_on }).\n" '422': "$ref": "#/components/responses/ValidationError" "/profile/bulk": patch: tags: - User Profile Management summary: Bulk update profile sections description: | Update multiple profile sections atomically in a single transaction. This ensures data consistency when updating related profile information. Called with an impersonation token, a request whose `personal` section carries a `phone`, `email` or `userid` value that differs from the stored one answers 403 `impersonation_cannot_change_account_security` and saves nothing; sending the stored values back unchanged is not refused. requestBody: required: true content: application/json: schema: type: object required: - updates properties: updates: type: object description: Profile sections to update properties: personal: type: object description: Personal information updates properties: first_name: type: string example: John last_name: type: string example: Doe phone: type: string example: "+1234567890" time_zone: type: string example: America/New_York employee_type: type: string example: Full-Time job_title: type: string example: Senior Developer department: type: string example: Engineering preferences: type: object description: Preferences updates by category properties: notifications: type: object example: shift_reminders: true schedule_changes: true availability: type: object example: willing_for_extra_shifts: true max_shifts_per_week: 5 communication: type: object example: preferred_method: email frequency: immediate professional: type: object description: Professional information updates properties: skills_for_roles: type: object example: developer: - JavaScript - React - Node.js custom_fields: type: object description: | The caller's own answers to the organization's custom profile fields, as `{ field_name: answer }`: a string, a list of strings for a multi-select, and true/false (or yes/no) for a yes-or-no field. Only fields the caller may answer themselves are accepted; a field that needs approval is refused with where to ask for it. Any refusal saves nothing in the whole update. additionalProperties: oneOf: - type: string - type: boolean - type: array items: type: string example: tshirt_size: L languages_spoken: - English - French example: updates: personal: phone: "+1234567890" time_zone: America/New_York preferences: notifications: shift_reminders: true schedule_changes: true availability: willing_for_extra_shifts: true max_shifts_per_week: 5 responses: '200': description: Bulk update completed successfully content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Bulk update completed successfully data: type: object properties: updated_sections: type: array items: type: string example: - personal - preferences results: type: object description: | Results for each updated section. `custom_fields` is `{ success, updated }`, the field names saved. '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/ImpersonationAccountSecurityForbidden" '422': description: | A section refused what was sent (`validation_failed`): `error.message` says why, and `error.details.errors` lists one sentence per refusal. Nothing in the update was saved. content: application/json: schema: "$ref": "#/components/schemas/Error" "/users/me/security": get: tags: - Account Settings summary: Get user security settings description: | Retrieve comprehensive security settings for the authenticated user including two-factor authentication status, trusted devices, security questions, and login history. responses: '200': description: Security settings retrieved successfully content: application/json: schema: type: object properties: security: "$ref": "#/components/schemas/UserSecuritySettings" '401': "$ref": "#/components/responses/Unauthorized" patch: tags: - Account Settings summary: Update user security settings description: | Update security settings including two-factor authentication, trusted devices, and security questions. requestBody: required: true content: application/json: schema: type: object properties: security: type: object properties: two_factor_auth: type: object properties: enabled: type: boolean description: Enable or disable two-factor authentication trusted_devices: type: object properties: remove_device_id: type: string description: ID of device to remove from trusted list security_questions: type: object properties: question_1: type: string description: First security question answer_1: type: string description: Answer to first security question question_2: type: string description: Second security question (optional) answer_2: type: string description: Answer to second security question (optional) responses: '200': description: Security settings updated successfully content: application/json: schema: type: object properties: security: "$ref": "#/components/schemas/UserSecuritySettings" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/ImpersonationAccountSecurityForbidden" '422': "$ref": "#/components/responses/ValidationError" "/account_settings/dashboard": get: tags: - Account Settings summary: Get account settings dashboard description: | Retrieve a comprehensive dashboard view of account settings including profile completion status, security overview, notification summary, and quick actions. responses: '200': description: Dashboard data retrieved successfully content: application/json: schema: type: object properties: dashboard: "$ref": "#/components/schemas/AccountSettingsDashboard" '401': "$ref": "#/components/responses/Unauthorized" "/account_settings/privacy": get: tags: - Account Settings summary: Get privacy settings description: | Retrieve privacy and data management settings including data sharing preferences, visibility settings, and data retention options. responses: '200': description: Privacy settings retrieved successfully content: application/json: schema: type: object properties: privacy: "$ref": "#/components/schemas/UserPrivacySettings" '401': "$ref": "#/components/responses/Unauthorized" patch: tags: - Account Settings summary: Update privacy settings description: | Update privacy and data management settings including data sharing, visibility preferences, and data retention options. requestBody: required: true content: application/json: schema: type: object properties: privacy: "$ref": "#/components/schemas/UserPrivacySettingsUpdate" responses: '200': description: Privacy settings updated successfully content: application/json: schema: type: object properties: privacy: "$ref": "#/components/schemas/UserPrivacySettings" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '422': "$ref": "#/components/responses/ValidationError" "/account_settings/communication": get: tags: - Account Settings summary: Get communication preferences description: | Retrieve communication preferences including language, timezone, communication style, AI assistant settings, and meeting preferences. responses: '200': description: Communication settings retrieved successfully content: application/json: schema: type: object properties: communication: "$ref": "#/components/schemas/UserCommunicationSettings" '401': "$ref": "#/components/responses/Unauthorized" patch: tags: - Account Settings summary: Update communication preferences description: | Update communication preferences including language, timezone, communication style, AI assistant settings, and meeting preferences. requestBody: required: true content: application/json: schema: type: object properties: communication: "$ref": "#/components/schemas/UserCommunicationSettingsUpdate" responses: '200': description: Communication settings updated successfully content: application/json: schema: type: object properties: communication: "$ref": "#/components/schemas/UserCommunicationSettings" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '422': "$ref": "#/components/responses/ValidationError" "/onboarding": get: tags: - Onboarding summary: Get onboarding progress description: | Returns the current user's onboarding status, progress percentage, and next steps. This endpoint provides a complete overview of the onboarding journey for mobile apps. **Required Scopes:** `read:own_profile` — the person's own first-run setup (#7183, owner rule 2026-10-06 "every api/v1 door asks a scope"). A token without it gets `403 insufficient_permissions` ("Required scope: read:own_profile") before anything else is checked. The sign-in tokens hold it; a browser session is asked no scope. responses: '200': description: Onboarding progress retrieved successfully content: application/json: schema: type: object properties: completed: type: boolean description: Whether onboarding is fully completed example: false current_step: type: string nullable: true description: The first step that applies to this person and is not yet done. `null` once `completed` is true. example: availability_shift_preferences progress_percentage: type: integer description: Completion percentage (0-100), over the steps that apply to this person example: 50 steps_completed: type: integer description: Number of applicable steps completed example: 2 steps_total: type: integer description: Number of steps that apply to this person (the ones `GET /onboarding/steps` lists) — steps skipped for the company or the person are not counted example: 4 estimated_completion_time: type: string description: Estimated time to complete remaining steps (3 minutes a step) example: 6 minutes next_action: type: string nullable: true description: URL for the next step to complete; `null` once completed example: "/api/v1/onboarding/steps/availability_shift_preferences" '401': "$ref": "#/components/responses/Unauthorized" '403': description: The token lacks `read:own_profile` (`insufficient_permissions`). content: application/json: schema: "$ref": "#/components/schemas/Error" "/onboarding/steps": get: tags: - Onboarding summary: List all onboarding steps description: "Returns a complete list of onboarding steps with their status, accessibility, \nand metadata. Useful for displaying progress indicators and step navigation.\n\nOnly the steps that apply to this person are listed: a step the company\ndoes not use, and `security_setup` for a person who signs in through\ntheir organization, are left out.\n\n**Required Scopes:** `read:own_profile` — the person's own first-run\nsetup (#7183, owner rule 2026-10-06 \"every api/v1 door asks a scope\").\nA token without it gets `403 insufficient_permissions` (\"Required scope:\nread:own_profile\") before anything else is checked. The sign-in tokens\nhold it; a browser session is asked no scope.\n" responses: '200': description: Onboarding steps retrieved successfully content: application/json: schema: type: object properties: steps: type: array items: type: object properties: name: type: string description: Step identifier example: profile_completion display_name: type: string description: Human-readable step name example: Complete Your Profile position: type: integer description: Step position in sequence example: 1 status: type: string enum: - pending - completed - skipped description: Current step status example: completed completed_at: type: string format: date-time nullable: true description: When step was completed accessible: type: boolean description: Whether step can be accessed now example: true required: type: boolean description: Whether step is required example: true estimated_time: type: string description: Estimated completion time example: 3-5 minutes description: type: string description: Step description example: Complete your basic profile information including name and contact details. url: type: string description: API URL for this step example: "/api/v1/onboarding/steps/profile_completion" total_count: type: integer description: Total number of steps listed example: 4 completed_count: type: integer description: Number of completed steps example: 2 '401': "$ref": "#/components/responses/Unauthorized" '403': description: The token lacks `read:own_profile` (`insufficient_permissions`). content: application/json: schema: "$ref": "#/components/schemas/Error" "/onboarding/steps/{step_name}": get: tags: - Onboarding summary: Get step details description: | Returns detailed information about a specific onboarding step including form fields, current data, validation rules, and help text. **What each step's `form_fields` publish:** - `profile_completion` — `first_name`, `last_name`, `phone`, `time_zone` (editable); `email` and `userid` (read-only, each only when the person has one); `job_title` (**read-only**: "Your job title is managed by your administrator."). There is no profile photo field — the step saves none. - `availability_shift_preferences` — `min_hours_weekly` and `max_hours_weekly` (`min: 0`, `max: 80`), `max_consecutive_days` (`min: 1`, `max: 7`), `weekend_availability` (`all`, `alternating`, `occasional`, `none`), `holiday_availability` (`all`, `some`, `none`) and `willing_for_extra_shifts`. - `notification_preferences` — `email_notifications` and `sms_notifications` only; either is `read_only: true` with the reason in `help_text` when that channel cannot reach the person. Shift reminder timing and quiet hours are no longer published as fields (`current_data` still carries `shift_reminder_hours`, `quiet_hours_start` and `quiet_hours_end` for apps that read them). - `security_setup` — `password`, `password_confirmation`, and `current_password` unless it is waived for this caller. **A skipped step** answers 200 with `status: "skipped"`, `skipped: true`, `skipped_reason`, `accessible: false`, `required: false` and `message` ("This step has been skipped: .") — and none of the form keys. The reason is one of: "Not part of this company's onboarding" (`role_location_assignment` and `secondary_location_preferences`, always), "You sign in through your organization, so there is no password to set" (`security_setup` for an SSO person), or "Your company doesn't use this step". **Required Scopes:** `read:own_profile` — the person's own first-run setup (#7183, owner rule 2026-10-06 "every api/v1 door asks a scope"). A token without it gets `403 insufficient_permissions` ("Required scope: read:own_profile") before anything else is checked. The sign-in tokens hold it; a browser session is asked no scope. parameters: - name: step_name in: path required: true description: Name of the onboarding step schema: type: string enum: - profile_completion - role_location_assignment - availability_shift_preferences - secondary_location_preferences - notification_preferences - security_setup example: profile_completion responses: '200': description: Step details retrieved successfully content: application/json: schema: type: object properties: name: type: string example: profile_completion display_name: type: string example: Complete Your Profile status: type: string enum: - pending - completed - skipped example: pending completed_at: type: string format: date-time nullable: true accessible: type: boolean example: true required: type: boolean example: true estimated_time: type: string example: 3-5 minutes description: type: string example: Complete your basic profile information including name and contact details. skipped: type: boolean description: Present (true) only when the step is skipped for this person example: true skipped_reason: type: string description: Why the step is skipped; present only on a skipped step example: Your company doesn't use this step message: type: string description: Present only on a skipped step example: 'This step has been skipped: Your company doesn''t use this step.' form_fields: type: array description: Form fields for this step (absent on a skipped step) items: type: object properties: name: type: string example: job_title type: type: string description: text, email, tel, password, number, boolean, select or multi_select example: text required: type: boolean example: false label: type: string example: Job Title read_only: type: boolean description: The step shows this field and saves no value for it example: true help_text: type: string description: Present on some fields (a read-only field's reason, a number field's range) example: Your job title is managed by your administrator. min: type: integer description: Number fields with a range only (hours 0, consecutive days 1) example: 0 max: type: integer description: Number fields with a range only (hours 80, consecutive days 7) example: 80 options: type: array description: Select fields only items: type: object properties: value: example: alternating label: type: string example: Prefer every other weekend current_data: type: object description: Current values for form fields example: first_name: John last_name: Doe email: john.doe@example.com userid: phone: "+12065550100" job_title: Shift Lead time_zone: Eastern Time (US & Canada) validation_rules: type: object description: Validation rules for form fields example: first_name: required: true min_length: 1 last_name: required: true min_length: 1 time_zone: required: true help_text: type: string nullable: true description: Help text for this step example: This information helps us personalize your experience and ensures you receive important communications. '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': description: Step not accessible, or the token lacks `read:own_profile` (`insufficient_permissions`). content: application/json: schema: "$ref": "#/components/schemas/Error" patch: tags: - Onboarding summary: Complete onboarding step description: | Updates and completes a specific onboarding step with the provided data. This will validate the input, save the data, and update the user's progress. **`profile_completion`** saves `user.first_name`, `last_name`, `phone` and `time_zone`. `email` is not written. `job_title` is read-only: a posted title that differs from the one the step published is not saved, the rest of the step still saves, and the reply names it in `blocked_fields: ["job_title"]`. Changing a verified `phone` ends its verification; where the organization sends texts and the person has not switched them off, the reply says so in `warnings`. **`availability_shift_preferences`** (under `availability_shift_preferences` or `user`) is refused with 422 when: - `min_hours_weekly` or `max_hours_weekly` is not a whole number — "Minimum hours per week must be a whole number between 0 and 80" / "Maximum hours per week must be a whole number between 0 and 80"; - `min_hours_weekly` or `max_hours_weekly` is outside 0–80 — "Minimum hours per week must be between 0 and 80" / "Maximum hours per week must be between 0 and 80"; - the minimum that will be stored is above the maximum that will be stored — "Minimum hours cannot be greater than maximum hours". An end that is not posted, or posted blank, is the one already stored; - `max_consecutive_days` is not a whole number — "Maximum consecutive days must be a whole number between 1 and 7"; - `max_consecutive_days` is outside 1–7 — "Maximum consecutive days must be between 1 and 7"; - `weekend_availability` is not `all`, `alternating`, `occasional` or `none`, or `holiday_availability` is not `all`, `some` or `none` — "… must be one of: ". A value posted back exactly as the person already holds it is never refused, whatever it is. The older words `never`, `sometimes` and `always` are still accepted and stored as `none`, `occasional` (weekend) / `some` (holiday) and `all`. Nothing is clamped. A blank is no answer: a blank `max_consecutive_days`, `weekend_availability` or `holiday_availability` clears the stored answer, and a blank or null `min_hours_weekly` / `max_hours_weekly` leaves the stored hours as they are. **`notification_preferences`** records `email_notifications` and `sms_notifications`. `shift_reminder_hours`, `quiet_hours_start` and `quiet_hours_end` are still accepted from older apps but are not published as fields. **A skipped step** answers 200 with `step_completed: true`, `step_skipped: true` and `message: "Step has been automatically skipped: "` (reasons as on `GET /onboarding/steps/{step_name}`) and saves nothing. **A refused save** answers 422 `step_processing_failed`; `error.message` is the first reason and `error.details` lists them all. **Required Scopes:** `update:own_profile` (#7183, owner rule 2026-10-06 "every api/v1 door asks a scope") — and, for the `security_setup` step, which sets the password, `write:connections` on top: the scope every door that changes a credential asks (#5087). A token without one gets `403 insufficient_permissions` ("Required scope: …") before anything is saved. The sign-in tokens hold all of them; a browser session is asked no scope. parameters: - name: step_name in: path required: true description: Name of the onboarding step schema: type: string enum: - profile_completion - role_location_assignment - availability_shift_preferences - secondary_location_preferences - notification_preferences - security_setup example: profile_completion requestBody: required: true content: application/json: schema: type: object description: Step-specific data (varies by step) example: user: first_name: John last_name: Doe phone: "+12065550100" time_zone: Eastern Time (US & Canada) responses: '200': description: Step completed successfully content: application/json: schema: type: object properties: step_completed: type: boolean example: true step_skipped: type: boolean description: Present (true) only when the step is skipped for this person and nothing was saved example: true message: type: string description: Present only with `step_skipped` example: 'Step has been automatically skipped: Your company doesn''t use this step' current_step: type: string nullable: true description: Step the person is on after this save. `null` once `onboarding_completed` is true. example: notification_preferences progress_percentage: type: integer example: 25 onboarding_completed: type: boolean example: false next_step: type: string nullable: true description: The next step after this one that is neither skipped nor already completed example: notification_preferences next_action: type: string nullable: true example: "/api/v1/onboarding/steps/notification_preferences" blocked_fields: type: array description: Posted fields the step did not save. Present only when there is one — today `job_title`, when a title other than the published one was posted. The step itself saved. items: type: string example: - job_title warnings: type: array description: Sentences to show the person about what the save changed. Present only when there is one — today, on `profile_completion`, when a verified phone number was changed or removed and text notifications to the person have stopped. The step itself saved. items: type: string example: - Text notifications are off until you verify your new number in Account Settings › Notifications. '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': description: | `step_not_accessible`: previous steps are not yet completed. `impersonation_cannot_complete_account_setup`: the request uses an impersonation token — no step is saved under one. `insufficient_permissions`: the token lacks `update:own_profile`, or — on the `security_setup` step — `write:connections`. `impersonation_cannot_change_account_security`: the request uses an impersonation token and either the step is `security_setup`, or the step is `profile_completion` and `user` carries a `phone`, `email` or `userid` value that differs from the stored one (sending the stored values back unchanged is not refused). content: application/json: schema: "$ref": "#/components/schemas/Error" '404': description: "`step_not_found`: the step name is not an onboarding step." content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: The step was not saved (`step_processing_failed`, or `step_completion_failed` / `step_skip_failed`). For `step_processing_failed`, `error.message` is the first reason and `error.details` lists every reason. content: application/json: schema: "$ref": "#/components/schemas/Error" example: error: code: step_processing_failed message: Maximum hours per week must be between 0 and 80 details: - Maximum hours per week must be between 0 and 80 "/onboarding/steps/{step_name}/enhanced": get: tags: - Onboarding summary: Get enhanced step information with AI assistance description: | Returns comprehensive step information including smart defaults, AI suggestions, and intelligent assistance. This endpoint consolidates multiple features: - Smart form pre-filling based on user context - AI-powered preference suggestions - Similar employee patterns and benchmarks - Contextual tips and completion guidance - Personalized time estimates The fields, ranges, option values and the skipped-step reply are those of `GET /onboarding/steps/{step_name}`: `job_title` is read-only, there is no profile photo field, and the notification step publishes Email and SMS only. Tips and suggestions name only what the step's form offers. **Required Scopes:** `read:own_profile` — the person's own first-run setup (#7183, owner rule 2026-10-06 "every api/v1 door asks a scope"). A token without it gets `403 insufficient_permissions` ("Required scope: read:own_profile") before anything else is checked. The sign-in tokens hold it; a browser session is asked no scope. parameters: - name: step_name in: path required: true description: Name of the onboarding step schema: type: string enum: - profile_completion - role_location_assignment - availability_shift_preferences - secondary_location_preferences - notification_preferences - security_setup example: profile_completion responses: '200': description: Enhanced step information retrieved successfully content: application/json: schema: type: object properties: name: type: string example: profile_completion display_name: type: string example: Complete Your Profile status: type: string enum: - pending - completed - skipped example: pending completed_at: type: string format: date-time nullable: true accessible: type: boolean example: true required: type: boolean example: true estimated_time: type: string example: 3-5 minutes description: type: string example: Complete your basic profile information including name and contact details. form_fields: type: array description: Enhanced form fields with smart suggestions. Each also carries `read_only`, and `help_text` / `min` / `max` / `options` where the plain step endpoint does. items: type: object properties: name: type: string example: time_zone type: type: string example: select required: type: boolean example: true label: type: string example: Time Zone read_only: type: boolean example: false suggested_value: type: string nullable: true description: On `time_zone` only example: Pacific Time (US & Canada) confidence: type: string enum: - medium - low description: On `time_zone` only — `medium` when the offered zone was detected, else `low` example: medium smart_help: type: string nullable: true description: Field-specific help, when the field has one current_data: type: object description: Current values with smart defaults applied example: first_name: John last_name: Doe email: john.doe@example.com userid: phone: job_title: Shift Lead time_zone: Pacific Time (US & Canada) ai_suggestions: type: object description: Suggestions and insights; the keys depend on the step (these are `profile_completion`'s; empty for steps with none) properties: timezone_confidence: type: string example: medium profile_completeness_score: type: integer example: 75 suggested_improvements: type: array items: type: string example: - Complete your phone number for emergency contact smart_defaults: type: object description: Intelligent defaults based on context properties: timezone_detected: type: string nullable: true example: Pacific Time (US & Canada) role_based_suggestions: type: object description: Empty when the person has no role example: role_name: Software Engineer common_locations: [] similar_employee_patterns: type: object description: Patterns from similar employees; an empty object when there is nobody to compare with properties: common_availability_patterns: type: object example: avg_min_hours: 20 avg_max_hours: 40 typical_completion_time: type: string nullable: true example: 2 days success_factors: type: array items: type: string example: - Complete profiles (85% average) - Email notifications enabled (78%) completion_tips: type: array description: Contextual tips for completing this step items: type: string example: - Setting your correct timezone ensures accurate scheduling - Complete contact information helps with emergency situations common_mistakes: type: array description: Common mistakes to avoid items: type: string example: - Forgetting to set timezone (causes scheduling issues) - Using incomplete contact information estimated_completion_time: type: string description: Personalized time estimate example: 3-5 minutes progress_context: type: object description: Progress context and benchmarks properties: steps_remaining: type: integer example: 3 estimated_total_time: type: string example: 12 minutes '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': description: Step not accessible, or the token lacks `read:own_profile` (`insufficient_permissions`). content: application/json: schema: "$ref": "#/components/schemas/Error" "/onboarding/steps/{step_name}/validate": post: tags: - Onboarding summary: Validate step data description: | Validates onboarding step data without saving it. Useful for real-time form validation in mobile apps before final submission. It refuses what saving the step refuses — for `availability_shift_preferences`, hours that are not a whole number or are outside 0–80, consecutive days outside 1–7, a minimum above the maximum, and a weekend or holiday answer that is not one of the options (`never` / `sometimes` / `always` are still accepted); a value the person already holds, posted back unchanged, is never refused. A `job_title` other than the published one is a warning, not an error: "Your job title is managed by your administrator, so it can't be changed here." A skipped step answers 200 with `valid: true`, `skipped: true` and `message`. **Required Scopes:** `update:own_profile`, like saving the step (#7183) — and, for the `security_setup` step, `write:connections` on top. A token without one gets `403 insufficient_permissions` ("Required scope: …"). The sign-in tokens hold all of them; a browser session is asked no scope. parameters: - name: step_name in: path required: true description: Name of the onboarding step schema: type: string enum: - profile_completion - role_location_assignment - availability_shift_preferences - secondary_location_preferences - notification_preferences - security_setup example: profile_completion requestBody: required: true content: application/json: schema: type: object description: Step-specific data to validate example: user: first_name: John last_name: Doe time_zone: Eastern Time (US & Canada) responses: '200': description: Validation successful content: application/json: schema: type: object properties: valid: type: boolean example: true message: type: string example: Validation successful warnings: type: array description: Non-blocking warnings; they ride a valid answer too (absent on a skipped step) items: type: string example: [] skipped: type: boolean description: Present (true) only when the step is skipped for this person '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': description: The token lacks `update:own_profile`, or — on the `security_setup` step — `write:connections` (`insufficient_permissions`); or the step is `security_setup` and the request uses an impersonation token (`impersonation_cannot_change_account_security`). content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Validation failed content: application/json: schema: type: object properties: valid: type: boolean example: false errors: type: object description: Field-specific validation errors example: max_hours_weekly: - Maximum hours per week must be between 0 and 80 max_consecutive_days: - Maximum consecutive days must be between 1 and 7 warnings: type: array description: Non-blocking validation warnings items: type: string example: - Your job title is managed by your administrator, so it can't be changed here. "/onboarding/reset": post: tags: - Onboarding summary: Reset onboarding progress description: | Resets the user's onboarding progress back to the beginning. The steps that apply are asked again (the password step is never re-opened), and the person's answers are kept — each step comes back with what they last answered. Requires confirmation. Refused under an impersonation token. **Required Scopes:** `update:own_profile` (#7183, owner rule 2026-10-06 "every api/v1 door asks a scope"). Starting over re-opens the person's own setup, which they can redo, so it asks no delete-level scope. A token without it gets `403 insufficient_permissions` ("Required scope: update:own_profile"). The sign-in tokens hold it; a browser session is asked no scope. requestBody: required: true content: application/json: schema: type: object required: - confirm properties: confirm: type: string description: Must be "true" to confirm reset example: 'true' responses: '200': description: Onboarding reset successfully content: application/json: schema: type: object properties: reset: type: boolean example: true message: type: string example: Account setup has been reset. Your answers are kept, so you can change them as you go. current_step: type: string description: The first step that applies to this person example: profile_completion next_action: type: string example: "/api/v1/onboarding/steps/profile_completion" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': description: The token lacks `update:own_profile` (`insufficient_permissions`), or the request uses an impersonation token (`impersonation_cannot_change_account_security`). content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: "`reset_failed`: the reset could not be saved; `error.details` lists the reasons." content: application/json: schema: "$ref": "#/components/schemas/Error" "/forms": get: tags: - Forms summary: List published forms (Forms to Fill Out page) description: "Returns all published forms for the business, matching exactly what appears\non the web **Forms to Fill Out** page (`/apps/forms/published`).\n\n- Ordered alphabetically by name (A→Z)\n- Excludes survey-category templates and forms linked to a Survey\n- No per-user permission filtering — all authenticated users see all published forms\n- Each item includes `page_count` (number of pages in the form)\n\n**\U0001F4CB Complete Forms API**: For full Forms App API documentation including\ntemplate management, public sharing, and integration endpoints, see the\ndedicated Forms App schema at `/api-docs/forms-app-schema.yaml`\n" security: - BearerAuth: [] parameters: - name: search in: query required: false description: Case-insensitive substring match on form name schema: type: string example: incident report - name: category in: query required: false description: Filter by form category slug schema: type: string example: safety - name: priority in: query required: false description: Filter by form priority schema: type: string enum: - urgent - high - normal - low example: high - name: page in: query required: false description: Page number for pagination (default 1) schema: type: integer minimum: 1 default: 1 - name: per_page in: query required: false description: Items per page, 1–50 (default 20) schema: type: integer minimum: 1 maximum: 50 default: 20 responses: '200': description: Published forms retrieved successfully content: application/json: schema: type: object properties: items: type: array items: "$ref": "#/components/schemas/FormSummaryItem" meta: "$ref": "#/components/schemas/PaginationMeta" '401': "$ref": "#/components/responses/Unauthorized" "/forms/my_submissions": get: tags: - Forms summary: List current user's form submissions (My Submissions tab) description: | Returns the authenticated user's own form submissions, matching the web **My Submissions** page (`/apps/forms/my_submissions`). - Ordered by `updated_at DESC` — most recently touched first - Scope: only submissions belonging to the current user and business - The `status` parameter filters by one submission status: | `status` value | Meaning | |---|---| | _(omit)_ or `all` | All Statuses | | `draft` | Saved Drafts | | `pending_completion` | Paused for someone else to complete | | `submitted` | Submitted | | `under_review` | Under Review | | `changes_requested` | Fields returned for correction | | `approved` | Approved | | `rejected` | Rejected | | `completed` | Every finished submission — approved, or sent on a form that needs no approval (what the web pages call Completed) | Each item's `status` is the stored status; `display_state` and `status_label` are what the web pages show — `completed` / "Completed" for a sent form that needs no approval. security: - BearerAuth: [] parameters: - name: status in: query required: false description: | Status filter. Omit or pass `all` for every status. Allowed values: all, draft, pending_completion, submitted, under_review, changes_requested, approved, rejected, completed, pending_review (every sent submission still waiting on a decision). schema: type: string enum: - all - draft - pending_completion - submitted - under_review - changes_requested - approved - rejected - completed - pending_review example: draft - name: search in: query required: false description: Case-insensitive substring match on form name schema: type: string example: safety audit - name: page in: query required: false description: Page number (default 1) schema: type: integer minimum: 1 default: 1 - name: per_page in: query required: false description: Items per page, 1–50 (default 20) schema: type: integer minimum: 1 maximum: 50 default: 20 responses: '200': description: Submissions retrieved successfully content: application/json: schema: type: object properties: items: type: array items: "$ref": "#/components/schemas/MySubmissionItem" meta: "$ref": "#/components/schemas/PaginationMeta" segment_counts: type: object description: Per-status tab badge counts. Present ONLY on the all view (status=all or omitted); absent when a specific status is requested. Counts honor the active `search` filter. `all` is the grand total across every status and may exceed the sum of the five buckets when submissions sit in a status without its own tab (e.g. pending_completion). properties: all: type: integer example: 7 draft: type: integer example: 1 submitted: type: integer example: 2 under_review: type: integer example: 1 approved: type: integer example: 2 rejected: type: integer example: 1 completed: type: integer example: 3 description: Every finished submission — what status=completed lists pending_review: type: integer example: 1 description: Every sent submission still waiting on a decision — what status=pending_review lists required: - all - draft - submitted - under_review - approved - rejected examples: all_statuses: summary: All statuses (default) value: items: - id: 1042 form_id: 7 form_name: Equipment Transfer form_description: Transfer equipment custody between sites form_category: operations status: draft status_label: Saved draft completion_percentage: 85 submitted_at: reviewed_at: review_notes: updated_at: '2026-06-11T16:30:00Z' created_at: '2026-06-10T08:00:00Z' is_offline_submission: false - id: 2232 form_id: 12 form_name: Site Safety Audit form_description: Quarterly site-level safety walkthrough form_category: safety status: submitted status_label: Submitted completion_percentage: 100 submitted_at: '2026-06-12T09:52:00Z' reviewed_at: review_notes: updated_at: '2026-06-12T09:52:00Z' created_at: '2026-06-12T09:00:00Z' is_offline_submission: false meta: total_count: 6 current_page: 1 total_pages: 1 per_page: 20 segment_counts: all: 6 draft: 1 submitted: 2 under_review: 1 approved: 1 rejected: 1 '401': "$ref": "#/components/responses/Unauthorized" '422': description: Invalid status value content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: invalid_status message: type: string example: 'status must be one of: draft, submitted, under_review, approved, rejected' "/forms/assignments": get: tags: - Forms summary: List the caller's open recurring-form assignments description: | Returns the current user's open form assignments — the mobile **Assigned** tab. Caller-scoped: never another user's assignments, never tenant-wide. **Derived, not stored.** There is no per-user assignment row in the Forms schema. A scheduled form only sends notifications when it runs; it does not write an assignment record or a `pending_completion` submission. An "assignment" here is therefore computed as an active schedule that names the caller, whose template is still accepting submissions, and whose audience still includes the caller — joined to the caller's own draft for that template. **Stale assignee lists are filtered out.** A schedule's assignee list is an admin-authored blob written when the schedule was saved and never revalidated, so it still names people who have since moved out of the target department, location, or group. This endpoint applies the **same delivery-time audience re-check** the scheduling job applies, so it lists only assignments the job itself would actually deliver. Excluded: paused schedules, schedules past their end date, and templates that are archived, unpublished, closed by schedule, or at their response cap. `403` when the Forms app is not enabled or not licensed for the tenant, matching the sibling Forms reads. security: - BearerAuth: [] parameters: - name: page in: query required: false schema: type: integer default: 1 minimum: 1 - name: per_page in: query required: false description: Clamped to 1..50. schema: type: integer default: 20 minimum: 1 maximum: 50 responses: '200': description: The caller's open assignments content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: integer description: Scheduled-form id — the assignment's identity. form_id: type: integer form_name: type: string form_description: type: string nullable: true form_category: type: string nullable: true priority: type: string nullable: true page_count: type: integer field_count: type: integer required_field_count: type: integer schedule_descriptor: type: string description: Human cadence, e.g. "Scheduled · every 2 weeks". example: Scheduled · weekly due_at: type: string format: date-time nullable: true description: | When the current cycle closes. The schema holds no per-occurrence due date, so this is the schedule's next reset — the deadline for "the check you do this cycle". The campaign's terminal bound is `ends_at`, kept separate so a weekly form is not reported as due months away. next_run_at: type: string format: date-time nullable: true last_run_at: type: string format: date-time nullable: true ends_at: type: string format: date-time nullable: true description: Schedule's terminal bound, or null when open-ended. draft_submission_id: type: integer nullable: true description: The caller's draft for this template, or null. completion_percentage: type: integer nullable: true description: Null when not started. status: type: string enum: - due_today - assigned_to_you - action_needed description: | `action_needed` when a draft exists (that outranks the date), else `due_today` when the cycle closes today, else `assigned_to_you`. action: type: string enum: - start - continue_draft meta: type: object properties: total_count: type: integer current_page: type: integer total_pages: type: integer per_page: type: integer example: items: - id: 73 form_id: 799 form_name: Employee Information Update form_description: Request changes to your personal information on file form_category: hr priority: normal page_count: 1 field_count: 4 required_field_count: 0 schedule_descriptor: Scheduled · weekly due_at: '2026-08-17T19:46:49Z' next_run_at: '2026-08-17T19:46:49Z' last_run_at: '2026-08-10T19:46:49Z' ends_at: '2026-12-12T19:46:49Z' draft_submission_id: completion_percentage: status: assigned_to_you action: start meta: total_count: 1 current_page: 1 total_pages: 1 per_page: 20 '401': "$ref": "#/components/responses/Unauthorized" "/forms/categories": get: tags: - Forms summary: List form categories with published-form counts description: | Returns the canonical list of form categories (the same set the web form builder and Forms to Fill Out filter use), each with the number of published forms in that category for the caller's business. - The full canonical list is always returned, including categories with `form_count: 0` - Items follow the platform's defined category order (not sorted by count or name) - `form_count` uses the same exclusions as `GET /api/v1/forms` (published only; excludes survey-category and survey-linked forms), so a category's `form_count` equals the `meta.total_count` of `GET /api/v1/forms?category=` - Categories are not tenant-configurable today security: - BearerAuth: [] responses: '200': description: Categories retrieved successfully content: application/json: schema: type: object properties: items: type: array items: "$ref": "#/components/schemas/FormCategoryItem" meta: type: object properties: total_count: type: integer description: Number of categories returned (the full canonical list) example: 14 examples: default: summary: Categories with published-form counts value: items: - value: general label: General form_count: 4 - value: safety label: Safety form_count: 2 - value: hr label: HR form_count: 6 - value: it label: IT form_count: 0 meta: total_count: 14 '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/forms/approvals": get: tags: - Forms summary: List submissions pending the current reviewer's approval description: | Returns form submissions awaiting review/approval — the mobile **Approvals** queue. Mirrors the web Submissions review queue. - **Who can open it.** Admins and Forms App Admins; managers, while the Forms Manage tier includes them; a form's owner, owning team or co-owner; anyone named as an approver on an active approval workflow, or on the step a submission is waiting on; and anyone with a direct report whose submission is waiting for a decision. Everyone else gets `403`. - **What each caller sees:** - **Admins and Forms App Admins** see the business-wide set awaiting a decision (statuses `submitted` and `under_review` on forms that require approval). - **Everyone else** sees that set narrowed to the rows they can decide — their reports', forms they own or co-own, and rows waiting on a step that names them. - A person a form's approval workflow names for the step a submission is on also sees that submission here; under a workflow only the current step's approver may approve it (others may reject or return fields). - Ordered **oldest-waiting-first** (longest in the queue at the top). - The home-screen pending-approval badge (`GET /api/v1/home` → `forms.pending_approval_count`) counts exactly this same per-role set. **Filters.** All are optional and compose with `AND`; omitting every one returns the unfiltered queue. They narrow the caller's already-authorized queue and can never widen it — `?user_id=` on a manager's queue can only pick one of their own reportees. A value that cannot be a filter (an unparseable date, an array/hash-shaped `?template_id[a]=b`) is **dropped** from the query: the response is a `200` with that filter simply not applied, never a `500` and never a silently-empty list. security: - BearerAuth: [] parameters: - name: overdue in: query required: false description: | `true` returns only submissions that have been awaiting review longer than the server-side review SLA (currently 7 days, measured on `submitted_at` falling back to `created_at`). Identical to the web review queue's Overdue filter. Do not hardcode the threshold on the client — read the per-item `overdue` flag instead. schema: type: boolean - name: template_id in: query required: false description: Only submissions of this form template schema: type: integer - name: user_id in: query required: false description: Only submissions from this submitter schema: type: integer - name: date_from in: query required: false description: | Inclusive start of the submitted-date window (`YYYY-MM-DD`), measured on the same clock as `submitted_at` (falling back to `created_at`). schema: type: string format: date - name: date_to in: query required: false description: Inclusive end of the submitted-date window (`YYYY-MM-DD`) schema: type: string format: date - name: search in: query required: false description: Case-insensitive match on the form name OR the submitter's name schema: type: string - name: page in: query required: false description: Page number (default 1) schema: type: integer minimum: 1 default: 1 - name: per_page in: query required: false description: Items per page, 1–50 (default 20) schema: type: integer minimum: 1 maximum: 50 default: 20 responses: '200': description: Pending approvals retrieved successfully content: application/json: schema: type: object properties: items: type: array items: "$ref": "#/components/schemas/ApprovalItem" meta: allOf: - "$ref": "#/components/schemas/PaginationMeta" - type: object properties: overdue_count: type: integer description: | Overdue submissions in the whole filtered set (not just this page) — badge the queue and populate an "Overdue" tile from this one call. example: 4 examples: queue: summary: Reviewer's pending queue value: items: - id: 2231 reference: "#2231" form_id: 7 form_name: Site Safety Audit form_description: Quarterly site-level safety walkthrough form_category: safety priority: high submitter: J. Rivera submitter_email: jrivera@example.com submitter_photo_url: https://officechat-dev.workforce.mangoapps.com/rails/active_storage/.../avatar.jpg status: under_review status_label: Under review requires_approval: true overdue: true submitted_at: '2026-06-18T09:00:00Z' waiting_since: '2026-06-18T09:00:00Z' updated_at: '2026-06-18T09:05:00Z' created_at: '2026-06-18T08:40:00Z' meta: total_count: 4 current_page: 1 total_pages: 1 per_page: 20 overdue_count: 4 '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/forms/{id}": get: tags: - Forms summary: Get form template for mobile rendering description: | Returns complete form template with fields optimized for mobile rendering. Includes a draft submission for offline support and mobile-specific configuration. The response includes all data needed to render the form offline and handle submissions. parameters: - name: id in: path required: true description: Form template ID schema: type: integer example: 123 - name: submission_id in: query required: false description: Chooses the source for each field's `submission_data` value (always present in the response). When supplied, values come from THIS submission (for resume/edit) — scoped to the caller's OWN submissions of this form; a blank, missing, or other-user submission_id yields `null`. When omitted, values come from the caller's DRAFT submission for this form; if there is no draft data, every field's `submission_data` is `null`. schema: type: integer example: 789 responses: '200': description: Form template retrieved successfully content: application/json: schema: type: object description: Form data optimized for rendering properties: template: "$ref": "#/components/schemas/FormTemplate" draft_submission: "$ref": "#/components/schemas/FormSubmission" nullable: true description: 'Existing draft submission for progress restoration. NOTE: the `submission_data` property is intentionally omitted here — each field in `fields[]` now carries its own `submission_data` (sourced from this draft or the requested submission), so the map is not repeated on this object.' mobile_config: type: object description: Mobile-specific rendering configuration properties: offline_capable: type: boolean description: Whether the form supports offline mode example: true voice_input_enabled: type: boolean description: Whether voice input is available example: true photo_capture_enabled: type: boolean description: Whether photo capture is available example: true gps_enabled: type: boolean description: Whether GPS location is required example: false estimated_time_minutes: type: integer description: Estimated completion time example: 10 theme: type: object description: The colour picked in the form's Design modal (a custom palette's Brand primary, or the chosen preset's). Both values are `null` when the form follows the business theme — keep the business branding. properties: brand_primary: type: string nullable: true description: The picked brand colour as a example: "#f5c518" brand_primary_fill: type: string nullable: true description: The same colour moved until white button text clears it (WCAG AA, 4.5:1) — the fill the phone web fill page paints behind its buttons, links and checked controls. `null` when the form follows the business theme. example: "#7d6302" prefill_data: type: object description: Pre-filled field values nullable: true additionalProperties: true required: - template - mobile_config '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/forms/{id}/preview": get: tags: - Forms summary: Preview a form (lightweight metadata + field list) description: | Lightweight preview of a form: header metadata plus the ordered field list with **label and type only** — no field configuration, validation, options, draft, or per-user state, and (unlike `GET /forms/{id}`) it does NOT create a draft submission. Use it to show a form's shape before the user opens it to fill. Access is gated like `GET /forms/{id}` (the Forms app must be enabled for the business and visible to the user — the same access model as the web), so the field structure of an inaccessible form is not exposed. parameters: - name: id in: path required: true description: Form template ID schema: type: integer example: 123 responses: '200': description: Form preview retrieved successfully content: application/json: schema: type: object properties: id: type: integer example: 123 name: type: string example: Site Safety Audit category: type: string nullable: true example: operations page_count: type: integer description: Number of pages (page_break count + 1) example: 2 field_count: type: integer description: Total number of fields (equals the size of `fields`) example: 12 estimated_time_minutes: type: integer description: Estimated time to complete, in minutes example: 8 shareable_link: type: string nullable: true description: 'Public share URL (`/f/{token}`) for the form, or `null` when the form is not publicly accessible (not published, sharing disabled, public access off, or no token issued). ' example: https://officechat.workforce.mangoapps.com/f/abc123 qr_code_image_url: type: string nullable: true description: 'Absolute URL of the form''s QR-code image (PNG), encoding the public share link. Present only when the form is publicly accessible (same gate as `shareable_link`); `null` otherwise. Keyed by the form''s public access token (not its numeric id) so a mobile client with no web session can load it directly. ' example: https://officechat.workforce.mangoapps.com/apps/forms/templates/Xlv6kQQt1RSiHKB0kQUsiPmLcVm_l2Cu/qr_code?format=png fields: type: array description: 'All fields in display (position) order, each with label and type only. No other field information is included. ' items: type: object properties: label: type: string nullable: true description: Field label (null for unlabeled fields such as page breaks) example: Full Name type: type: string description: Field type example: text required: - type example: - label: Full Name type: text - label: Site type: select - label: type: page_break - label: Notes type: textarea required: - id - name - page_count - field_count - estimated_time_minutes - fields '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" "/forms/{id}/submit": post: tags: - Forms summary: Submit completed form description: | Submit a completed form, either as a new submission or sync from offline mode. Supports both immediate submission and offline sync scenarios. For offline sync, include submission_id and set offline_sync=true. Media fields (file / image / video / audio / signature / gallery): send the request as `multipart/form-data` and put the FILE PART in the field's own key — `submission[submission_data][site_photo]=@photo.jpg` for a single field, `submission[submission_data][damage_photos][]=@…` (repeated) for a gallery. Works with every authentication method, Bearer tokens included. The same shape is accepted by `POST /forms/{id}/submissions` and `PATCH /form_submissions/{id}`. The server validates every file (all-or-nothing, 422 `invalid_attachments` on an unsupported type, a file over the field's size limit, a file posted into a field that does not take one, or a file posted under a key that is not a field on this form at all), caps one request at 50 file parts, stores them, creates the file records, and rewrites those keys to a `{ uploaded, file_id, filename, content_type, file_size }` reference. A payload that carries NOTHING but file parts leaves every stored answer alone — it reads as "add these files", not as "replace the answers with nothing". Clearing a draft's answers is an explicit `submission_data: {}` (JSON), as it always was. Values already in reference form are left as-is (re-send them to keep a gallery's existing photos). A blob `signed_id` string is also accepted in the same key for a client that already holds one; the generic `POST /rails/active_storage/direct_uploads` endpoint is disabled (403) and is not a way to obtain one. parameters: - name: id in: path required: true description: Form template ID schema: type: integer example: 123 - name: submission_id in: query required: false description: Existing draft submission ID (for offline sync) schema: type: integer example: 456 - name: offline_sync in: query required: false description: Indicates this is an offline sync operation schema: type: boolean default: false requestBody: required: true content: application/json: schema: type: object properties: submission: type: object properties: submission_data: type: object description: Form field values as key-value pairs example: employee_name: John Doe incident_date: '2024-01-15' description: Equipment malfunction in warehouse device_id: type: string description: Mobile device identifier example: mobile-123abc required: - submission multipart/form-data: schema: type: object description: 'The same body, form-encoded — and the ONLY content type a file part can be sent on (a `format: binary` property inside a JSON-only requestBody is something no generated client, and no Swagger UI, can post). Each field takes its bracketed name: `submission[submission_data][full_name]` for an answer, `submission[submission_data][site_photo]` for a single file, repeated `submission[submission_data][damage_photos][]` for a gallery. At most 50 file parts per request.' properties: submission[submission_data][]: type: string format: binary description: The file for a single-file media field (file / image / video / audio / signature). The server validates it (all-or-nothing), stores it, creates the file record and rewrites the key to a `{ uploaded, file_id, filename, content_type, file_size }` reference. A file posted under a key that is not a media field on this template is refused with 422 `invalid_attachments`. submission[submission_data][][]: type: array items: type: string format: binary description: Repeated file parts for a gallery / multi-file field. Send the already-uploaded photos' reference hashes back in the same key to keep them. submission[submission_data][]: type: string description: Any non-media answer, form-encoded. responses: '201': description: Form submitted successfully content: application/json: schema: type: object properties: message: type: string example: Form submitted successfully submission: "$ref": "#/components/schemas/FormSubmission" sync_status: type: string enum: - immediate - synced example: immediate _meta: "$ref": "#/components/schemas/ResponseMeta" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '422': "$ref": "#/components/responses/ValidationError" "/forms/{id}/submissions": post: tags: - Forms summary: Create or update draft submission description: | Create a new draft submission or update an existing one for offline support. This endpoint allows mobile apps to save form progress locally and sync later. Pass `offline_sync=true` ONLY when saving a draft that was composed while the device was offline; an online client should omit it (or send false) so the draft is not mislabeled as an offline submission. On an existing draft the flag can only be turned on — an online edit never downgrades a draft that was genuinely created offline. parameters: - name: id in: path required: true description: Form template ID schema: type: integer example: 123 - name: offline_sync in: query required: false description: Set true only when saving a draft created while offline. Defaults to online (false). schema: type: boolean default: false requestBody: required: true content: application/json: schema: type: object properties: submission: type: object properties: submission_data: type: object description: Partial form field values example: employee_name: John Doe incident_date: '2024-01-15' required: - submission multipart/form-data: schema: type: object description: 'The same body, form-encoded — and the ONLY content type a file part can be sent on (a `format: binary` property inside a JSON-only requestBody is something no generated client, and no Swagger UI, can post). Each field takes its bracketed name: `submission[submission_data][full_name]` for an answer, `submission[submission_data][site_photo]` for a single file, repeated `submission[submission_data][damage_photos][]` for a gallery. At most 50 file parts per request.' properties: submission[submission_data][]: type: string format: binary description: The file for a single-file media field (file / image / video / audio / signature). The server validates it (all-or-nothing), stores it, creates the file record and rewrites the key to a `{ uploaded, file_id, filename, content_type, file_size }` reference. A file posted under a key that is not a media field on this template is refused with 422 `invalid_attachments`. submission[submission_data][][]: type: array items: type: string format: binary description: Repeated file parts for a gallery / multi-file field. Send the already-uploaded photos' reference hashes back in the same key to keep them. submission[submission_data][]: type: string description: Any non-media answer, form-encoded. responses: '201': description: Draft submission created successfully content: application/json: schema: type: object properties: message: type: string example: Draft saved successfully submission: "$ref": "#/components/schemas/FormSubmission" _meta: "$ref": "#/components/schemas/ResponseMeta" '200': description: Draft submission updated successfully content: application/json: schema: type: object properties: message: type: string example: Draft saved successfully submission: "$ref": "#/components/schemas/FormSubmission" _meta: "$ref": "#/components/schemas/ResponseMeta" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '422': "$ref": "#/components/responses/ValidationError" "/forms/submissions/{id}": delete: tags: - Forms summary: Delete a draft submission description: | Delete a form submission. Two gates apply, in order: 1. **Owner-only** — only the user who CREATED the submission may delete it (a reviewer/admin cannot delete someone else's draft here) → `403` with error code `access_denied`. 2. **Draft-only** — the submission must still be a `draft`. Once it is submitted / under_review / approved / rejected it is part of the review record and cannot be deleted → `422` with error code `cannot_delete` (the current `status` is returned in `error.details`). Deleting cascades to the submission's uploaded files. Requires the `write:forms` scope. (The same submission's GET and PATCH are also available at `/form_submissions/{id}`.) security: - BearerAuth: [] parameters: - name: id in: path required: true description: Form submission ID schema: type: integer example: 456 responses: '200': description: Draft submission deleted content: application/json: schema: type: object properties: message: type: string example: Draft submission deleted _meta: "$ref": "#/components/schemas/ResponseMeta" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '422': "$ref": "#/components/responses/ValidationError" "/form_submissions/{id}": get: tags: - Forms summary: Get submission details description: | Get details of a specific form submission including all field values and files. Used to view completed submissions and track submission status. Access mirrors the web Submissions surface: the submission's owner, or any admin / manager / Forms App Admin in the business, may view it. Any other user receives 403. Sensitive (manager-/submitter-restricted) field values are stripped from `submission_data` for viewers not permitted to see them. **submission_data shape (this endpoint only):** unlike the write/draft endpoints (which return a flat `field_name → value` map), the detail response expands each answer into an object carrying the field's `label`, submitted `value`, and `type` — `{ field_name: { label, value, type } }`. Keys are ordered by the template's field position (matching the web detail view), with any orphaned data (no matching field) appended last. The response's `submission.submitted_by` carries the submitter's name + email + photo_url. parameters: - name: id in: path required: true description: Form submission ID schema: type: integer example: 456 responses: '200': description: Submission retrieved successfully content: application/json: schema: type: object properties: submission: allOf: - "$ref": "#/components/schemas/FormSubmission" - "$ref": "#/components/schemas/FormSubmissionDecisionCapabilities" - type: object properties: can_approve: type: boolean description: 'May this caller approve it now (`Forms::SubmissionAccess#approvable?`) — false for someone who may not decide it, on a decided row, and for a reviewer whose workflow step it is not. Needs `write:forms`. ' submitted_by: type: object nullable: true description: 'Who submitted the form — name + email + photo. Resolves to the respondent email (or "Anonymous User") for anonymous submissions. photo_url is the submitter''s thumbnail avatar (a ui-avatars fallback when no photo is set), or null for anonymous submissions. ' properties: name: type: string nullable: true email: type: string nullable: true photo_url: type: string nullable: true submission_data: type: object description: 'Per-field answers keyed by field_name. Each value is an object with the field''s label, submitted value, and type (the expanded detail shape, not the flat write-endpoint map). ' additionalProperties: type: object properties: label: type: string nullable: true description: Field label from the template definition value: nullable: true description: 'Submitted value — a string or array for simple fields; a file-reference object/array for media fields (each reference includes a `url` to view/download the file); and, for `matrix` and Likert-mode `scale` fields, an ORDERED array of { label, value } pairs where `label` is the creator''s row/statement label and `value` is the chosen column/option label (an array of labels for a checkbox-grid or multiple-select matrix row). Pairs are returned in the creator''s configured row/statement order. A range-mode `scale` returns a plain scalar. ' type: type: string nullable: true description: Field type (text, image, gallery, signature, select, …) example: site_photo: label: Site photo type: image value: uploaded: true file_id: 36 filename: photo.png content_type: image/png file_size: 20480 url: "/rails/active_storage/blobs/redirect/eyJf…/photo.png" notes: label: Notes type: textarea value: All clear on the east wing. form: type: object description: Summary information for a form template properties: id: type: integer description: Unique form template ID example: 123 name: type: string description: Form name example: Incident Report description: type: string description: Form description example: Report workplace incidents and safety concerns category: type: string description: Form category example: safety priority: type: string enum: - urgent - high - normal - low description: Form priority level example: high status: type: string enum: - draft - published - archived description: Template status example: published field_count: type: integer description: Total number of fields in the form example: 8 required_field_count: type: integer description: Number of required fields example: 5 estimated_time_minutes: type: integer description: Estimated completion time in minutes example: 10 has_file_uploads: type: boolean description: Whether the form supports file uploads example: true sharing_enabled: type: boolean description: Whether the form can be shared publicly example: false requires_approval: type: boolean description: Whether submissions require approval example: true created_at: type: string format: date-time description: Form creation timestamp example: '2024-01-15T10:00:00Z' updated_at: type: string format: date-time description: Last update timestamp example: '2024-01-15T10:00:00Z' required: - id - name - category - priority - status - field_count - estimated_time_minutes timeline: type: array description: | Status timeline shown on the web "View details" page. Begins with a "Form Submitted" event once sent, followed by a single review event reflecting the current state (approved / fields returned for correction / rejected) when reviewed. A draft its sender withdrew carries a `withdrawn` event; a submission waiting for a decision again carries `reopened_for_review` (an approval taken back) and/or `returns_taken_back` (a return for correction taken back), each with who did it and their reason in `note`. items: "$ref": "#/components/schemas/SubmissionTimelineEvent" workflow_step_runs: type: array description: | What each step of the form's workflow did for this submission, newest first, at most 20: the "Workflow steps" card on the web and phone submission pages. Only people who manage the form see it (admins, Forms app admins, and the form's creator, owner, owning team and co-owners); for everyone else it is an empty array. items: type: object properties: id: type: integer step_name: type: string nullable: true description: The step's name; null for an unnamed step. step_label: type: string description: What the web card prints for the step — its name, or "Unnamed step" in the reader's language. example: Email the safety lead outcome: type: string enum: - done - skipped - failed outcome_label: type: string example: Skipped detail: type: string nullable: true description: What the step produced, why it was skipped, or the error (up to 500 characters). trigger_status: type: string description: The submission status that ran the step. example: approved trigger_label: type: string description: That status in words, in the reader's language; the web card reads it as "When approved". example: Approved created_at: type: string format: date-time _meta: "$ref": "#/components/schemas/ResponseMeta" '401': "$ref": "#/components/responses/Unauthorized" '403': description: | Forbidden — not the owner and not an admin/manager/Forms App Admin (`forbidden`). Someone the submission ASKED to decide it who may no longer open it is told why instead: that it was withdrawn, returned, rejected or approved ("Nothing on this submission is waiting on you any more — it was rejected."), or that their own access to it ended. '404': "$ref": "#/components/responses/NotFound" patch: tags: - Forms summary: Update draft submission description: | Update a draft form submission for offline editing and progress saving. Only the submitter's own draft or rejected submissions can be updated. A submission returned for changes (`changes_requested`) answers 422 `returned_report_no_draft` — send the corrections with `POST /forms/{id}/submit`. A draft on a form that is no longer accepting submissions answers 403 `form_not_available`, and one whose audience no longer includes the caller 403 `access_denied`. parameters: - name: id in: path required: true description: Form submission ID schema: type: integer example: 456 requestBody: required: true content: application/json: schema: type: object properties: submission: type: object properties: submission_data: type: object description: Updated form field values example: employee_name: John Doe incident_date: '2024-01-15' description: Updated description required: - submission multipart/form-data: schema: type: object description: 'The same body, form-encoded — and the ONLY content type a file part can be sent on (a `format: binary` property inside a JSON-only requestBody is something no generated client, and no Swagger UI, can post). Each field takes its bracketed name: `submission[submission_data][full_name]` for an answer, `submission[submission_data][site_photo]` for a single file, repeated `submission[submission_data][damage_photos][]` for a gallery. At most 50 file parts per request.' properties: submission[submission_data][]: type: string format: binary description: The file for a single-file media field (file / image / video / audio / signature). The server validates it (all-or-nothing), stores it, creates the file record and rewrites the key to a `{ uploaded, file_id, filename, content_type, file_size }` reference. A file posted under a key that is not a media field on this template is refused with 422 `invalid_attachments`. submission[submission_data][][]: type: array items: type: string format: binary description: Repeated file parts for a gallery / multi-file field. Send the already-uploaded photos' reference hashes back in the same key to keep them. submission[submission_data][]: type: string description: Any non-media answer, form-encoded. responses: '200': description: Draft submission updated successfully content: application/json: schema: type: object properties: message: type: string example: Draft updated successfully submission: "$ref": "#/components/schemas/FormSubmission" _meta: "$ref": "#/components/schemas/ResponseMeta" '400': "$ref": "#/components/responses/BadRequest" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '422': "$ref": "#/components/responses/ValidationError" "/form_submissions/{id}/approve": post: tags: - Forms summary: Approve a form submission description: | Approve a submission that is awaiting review, mirroring the web **Approval** flow (Approve action) and the native Approvals screen (swipe-right / "Approve"). **Authorization:** the caller must be able to decide this submission — the rule the web uses (`Forms::SubmissionAccess#decidable?`): an admin or Forms App Admin, one of the form's own people (owner, owning team, co-owners, or its creator while inside the Forms Manage tier), the submitter's manager, or a person the form's approval workflow names for the step the submission is on (`write:forms` scope). A person named on another step of its workflow receives `403` with code `not_current_approver`. Its message names the step the submission is waiting on and that step's approvers only to a caller who may read the submission; otherwise it says the submission isn't at their step yet, or that it isn't waiting on them. Anyone else receives `403`. **Preconditions:** - The submission must be **awaiting review** (`submitted` or `under_review`), else `422` with code `invalid_state`. - Approval is blocked while any field is still returned to the employee for field-level correction (`422` with code `open_returns`). Sets `status = approved`, stamps `reviewed_by` / `reviewed_at`, and optionally records `review_notes`. The submitter is emailed a status-changed notification (best-effort). parameters: - name: id in: path required: true description: Form submission ID schema: type: integer example: 456 requestBody: required: false content: application/json: schema: type: object properties: review_notes: type: string description: Optional approval note recorded on the submission. example: Approved — all required documents attached. responses: '200': description: Submission approved content: application/json: schema: type: object properties: message: type: string example: Submission approved submission: "$ref": "#/components/schemas/ReviewedSubmission" _meta: "$ref": "#/components/schemas/ResponseMeta" '401': "$ref": "#/components/responses/Unauthorized" '403': description: | Forbidden — token lacks `write:forms` scope (`insufficient_permissions`) or the caller is not a reviewer (`access_denied`). content: application/json: schema: "$ref": "#/components/schemas/Error" '404': "$ref": "#/components/responses/NotFound" '422': description: | Submission is not awaiting review (`invalid_state`) or fields are still returned to the employee (`open_returns`). content: application/json: schema: "$ref": "#/components/schemas/Error" "/form_submissions/{id}/reject": post: tags: - Forms summary: Reject a form submission description: | Reject a submission that is awaiting review, mirroring the web reject modal and the native reject-note bottom sheet (swipe-left / "Reject…"). **Authorization:** the caller must be able to decide this submission — the rule the web uses (`Forms::SubmissionAccess#decidable?`): an admin or Forms App Admin, one of the form's own people (owner, owning team, co-owners, or its creator while inside the Forms Manage tier), the submitter's manager, or a person the form's approval workflow names for the step the submission is on (`write:forms` scope). A person named on another step of its workflow receives `403` with code `not_current_approver`. Its message names the step the submission is waiting on and that step's approvers only to a caller who may read the submission; otherwise it says the submission isn't at their step yet, or that it isn't waiting on them. Anyone else receives `403`. **Preconditions:** - `review_notes` (the rejection reason) is **required**; a missing or blank/whitespace-only value returns `422` with code `review_notes_required`. The note is shown to the submitter so they can correct and resubmit. - The submission must be **awaiting review** (`submitted` or `under_review`), else `422` with code `invalid_state`. Sets `status = rejected`, stamps `reviewed_by` / `reviewed_at`, and stores `review_notes`. The submitter is emailed a status-changed notification (best-effort). Delete-level (owner decision 2026-10-04, #6721): requires the `destructive:forms` scope. parameters: - name: id in: path required: true description: Form submission ID schema: type: integer example: 456 requestBody: required: true content: application/json: schema: type: object properties: review_notes: type: string description: Reason for rejection (required). Shown to the submitter. example: The incident date is missing — please add it and resubmit. required: - review_notes responses: '200': description: Submission rejected content: application/json: schema: type: object properties: message: type: string example: Submission rejected submission: "$ref": "#/components/schemas/ReviewedSubmission" _meta: "$ref": "#/components/schemas/ResponseMeta" '401': "$ref": "#/components/responses/Unauthorized" '403': description: | Forbidden — token lacks `write:forms` scope (`insufficient_permissions`) or the caller is not a reviewer (`access_denied`). content: application/json: schema: "$ref": "#/components/schemas/Error" '404': "$ref": "#/components/responses/NotFound" '422': description: | `review_notes` is missing or blank (`review_notes_required`), or the submission is not awaiting review (`invalid_state`). content: application/json: schema: "$ref": "#/components/schemas/Error" "/form_submissions/{id}/return_fields": post: tags: - Forms summary: Return individual fields for correction description: | The reviewer's **third option**, alongside approve and reject: return NAMED fields to the submitter with a per-field comment, instead of rejecting a whole submission over a couple of bad answers. The submitter then corrects only those fields — everything else stays locked and answered. Shares its implementation with the web reviewer action (`PATCH /apps/forms/submissions/:id/return_fields`) — same returnable-field rules, same preconditions, same notifications — so the two surfaces cannot drift on what a return does. **Authorization:** the caller must be able to decide this submission — the rule the web uses (`Forms::SubmissionAccess#decidable?`): an admin or Forms App Admin, one of the form's own people (owner, owning team, co-owners, or its creator while inside the Forms Manage tier), the submitter's manager, or a person the form's approval workflow names for the step the submission is on (the token must carry `write:forms`). A person named on another step of its workflow receives `403` with code `not_current_approver`. Its message names the step the submission is waiting on and that step's approvers only to a caller who may read the submission; otherwise it says the submission isn't at their step yet, or that it isn't waiting on them. Anyone else receives `403`. **Preconditions:** - The submission must be **awaiting review** (`submitted` or `under_review`), else `422` with code `not_awaiting_review`. - There must be someone to return it to. An **anonymous** submission (public portal) returns `422` with code `anonymous_submission`; one sent without an account (a candidate's assessment, a job application) `submitter_has_no_account`; a submitter who is no longer an active member of the organization `submitter_not_member`; a customer's answers to an Implementation Hub project's form request go back through the request (it is reopened and the customer told), and once no request holds them or the project is closed to the customer the call returns `request_closed`, or `submitter_left_team` when the person whose copy it is has left the customer's team — approve or reject it instead. `can_return_fields` on the submission says which. - At least one **returnable** field must carry a **non-blank comment**, else `422` with code `no_returnable_fields`. **Fields that are never returnable** — dropped server-side, never applied, and named back in `ignored_fields`: - file / media fields (`file`, `image`, `video`, `audio`, `gallery`) and `annotation` — the corrections form cannot re-process an upload - any field this reviewer is not permitted to READ (field-level visibility) - any name that is not a field on the form - any field supplied with a blank comment **Effects:** `status` → `changes_requested`, `review_round` incremented by 1, a `field_reviews` entry written per returned field (state / comment / round / history), every other answered field this reviewer may read marked `accepted` (named in `accepted_fields`), and `reviewed_by` / `reviewed_at` stamped. The submitter receives an in-app *action required* notification **and** an email (best-effort — a delivery failure never fails the call). A subsequent `GET /api/v1/forms/{form_id}?submission_id={id}` reflects the new `returned_field_names`, each field's `field_review`, and `is_editable: false` on the fields that were not returned. parameters: - name: id in: path required: true description: Form submission ID schema: type: integer example: 4812 requestBody: required: true content: application/json: schema: type: object properties: field_returns: type: object description: | `{ field_name: comment }`. The comment is REQUIRED per field and is shown to the submitter — a blank comment does not return the field. additionalProperties: type: string example: incident_location: Please give the bay number, not just 'warehouse'. witness_name: Left blank — required if anyone else was present. review_notes: type: string description: Optional submission-level note recorded on the submission. example: Two fields need detail before I can approve. required: - field_returns responses: '200': description: Fields returned to the submitter for correction content: application/json: schema: type: object properties: message: type: string example: Returned 2 answers for correction submission: "$ref": "#/components/schemas/ReviewedSubmission" ignored_fields: type: array description: | Names the request asked to return that the server dropped — non-returnable, unknown, or supplied with a blank comment. **Omitted entirely when nothing was dropped.** Same key and same meaning as on the submission write paths. items: type: string example: - site_photo warning: type: string description: Human-readable companion to `ignored_fields`; omitted when nothing was dropped. _meta: "$ref": "#/components/schemas/ResponseMeta" '401': "$ref": "#/components/responses/Unauthorized" '403': description: | Forbidden — token lacks `write:forms` scope (`insufficient_permissions`) or the caller is not a reviewer (`access_denied`). content: application/json: schema: "$ref": "#/components/schemas/Error" '404': "$ref": "#/components/responses/NotFound" '422': description: | Submission is not awaiting review (`not_awaiting_review`), was submitted anonymously (`anonymous_submission`) or without an account (`submitter_has_no_account`), its submitter is no longer a member (`submitter_not_member`) or no longer on the customer's team (`submitter_left_team`), its project's form request is closed (`request_closed`), no returnable field carried a comment (`no_returnable_fields`, whose `details.ignored_fields` names what was dropped), or the return could not be saved (`return_failed`). content: application/json: schema: "$ref": "#/components/schemas/Error" "/form_submissions/{id}/withdraw": post: tags: - Forms summary: Withdraw a submission waiting for review description: | The submitter takes back their own submission while it waits for a decision; it becomes a draft again to correct and send (`MaForms::FormSubmission#withdraw!` — the web's **Withdraw**). The reviewers' open asks close. Refused (`422 cannot_withdraw`, with the reason as the message and the current `status` in `error.details`) when the caller did not send it, it is not waiting for review, an approval-workflow step was already signed, it was filed to HR Files, it belongs to an onboarding plan item, or its form no longer accepts responses. `can_withdraw` / `withdraw_refusal` on the submission say which in advance. Requires `write:forms`. parameters: - name: id in: path required: true description: Form submission ID schema: type: integer example: 4812 responses: '200': description: Withdrawn — the submission is a draft again content: application/json: schema: type: object properties: message: type: string example: Submission withdrawn — it is a draft again submission: "$ref": "#/components/schemas/ReviewedSubmission" _meta: "$ref": "#/components/schemas/ResponseMeta" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '422': description: The submission can't be withdrawn (`cannot_withdraw`) or could not be saved. content: application/json: schema: "$ref": "#/components/schemas/Error" "/form_submissions/{id}/reopen": post: tags: - Forms summary: Reopen an approved submission for review description: | Takes an approval made by mistake back to **Under review** (`MaForms::FormSubmission#reopen_for_review!` — the web's **Reopen for review**). `reason` is required; the submitter is told it, and whoever may decide the submission now is asked again (not the caller, unless nobody else may). Refused (`422 cannot_reopen`, the reason as the message) unless the caller may approve it and the approval has had no effect reopening cannot undo — a multi-step workflow's sign-offs, a document filed to HR Files, a verified onboarding item, or a workflow rule for approved submissions that already ran. `can_reopen` / `reopen_refusal` on the submission say which in advance. Requires `write:forms`. parameters: - name: id in: path required: true description: Form submission ID schema: type: integer example: 4812 requestBody: required: true content: application/json: schema: type: object properties: reason: type: string maxLength: 1000 description: Why it is reopened — shown to the submitter. example: Approved the wrong row from the list. required: - reason responses: '200': description: Reopened — the submission waits for a decision again content: application/json: schema: type: object properties: message: type: string example: Submission reopened for review submission: "$ref": "#/components/schemas/ReviewedSubmission" _meta: "$ref": "#/components/schemas/ResponseMeta" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '422': description: | The submission can't be reopened (`cannot_reopen`), `reason` is missing (`reason_required`), or it could not be saved. content: application/json: schema: "$ref": "#/components/schemas/Error" "/form_submissions/{id}/take_back_returns": post: tags: - Forms summary: Take back a return for correction description: | A reviewer takes back a return for correction (`MaForms::FormSubmission#take_back_returns!` — the web's **Take back the return**): the submission waits for a decision again with its answers as sent, the submitter's "correct these answers" ask closes and they are told why, and whoever may decide it now is asked (not the caller, unless nobody else may). `reason` is required. Refused (`422 cannot_take_back`, the reason as the message) unless it is returned for correction and the caller manages it or is the reviewer who returned it while still signing its current step — and never on an onboarding plan item's form (the new hire corrects it in their onboarding plan). `can_take_back_returns` / `take_back_returns_refusal` on the submission say which in advance. Requires `write:forms`. parameters: - name: id in: path required: true description: Form submission ID schema: type: integer example: 4812 requestBody: required: true content: application/json: schema: type: object properties: reason: type: string maxLength: 1000 description: Why the return is taken back — shown to the submitter. example: Returned the wrong answers — they were fine. required: - reason responses: '200': description: Return taken back — the submission is under review again content: application/json: schema: type: object properties: message: type: string example: Return taken back — the submission is under review again submission: "$ref": "#/components/schemas/ReviewedSubmission" _meta: "$ref": "#/components/schemas/ResponseMeta" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '404': "$ref": "#/components/responses/NotFound" '422': description: | The return can't be taken back (`cannot_take_back`), `reason` is missing (`reason_required`), or it could not be saved. content: application/json: schema: "$ref": "#/components/schemas/Error" "/marketplace_apps": get: tags: - Marketplace Apps summary: List enabled marketplace apps description: | Returns a list of marketplace apps that are enabled for the authenticated user's business. This endpoint provides all data needed to display a grid view of apps in a mobile client, including app icons, names, descriptions, and launch URLs. Apps are returned in the business's app order (the apps its admin numbered in Sort Order first, then the rest by the catalogue's rank), the order the web lists them in; each app's `sort_order` is its place in that order, starting at 1. They include configuration data specific to the business. **Required Scopes:** `read:organization` (#7183, owner rule 2026-10-06 "every api/v1 door asks a scope"). A token without it gets `403 insufficient_permissions` ("Required scope: read:organization") before anything else is checked. Every sign-in token holds it, and so does a token a person makes by hand from this deploy on; a token made by hand before this deploy may not. A browser session is asked no scope. parameters: - name: include_metadata in: query required: false description: Whether to include app metadata in response schema: type: boolean default: false responses: '200': description: Enabled marketplace apps retrieved successfully content: application/json: schema: type: object properties: apps: type: array items: "$ref": "#/components/schemas/MarketplaceApp" total_count: type: integer description: Total number of enabled apps example: 5 _meta: "$ref": "#/components/schemas/ResponseMeta" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/core_apps": get: tags: - System Modules summary: List enabled core apps description: | Returns a list of core platform apps and their enabled status for the authenticated user's business. Core apps are fundamental platform features like Shifts & Scheduling, Time & Attendance, etc. that can be enabled or disabled at the business level. This endpoint provides all data needed to display core app status in a mobile client, including app icons, descriptions, feature lists, and direct URLs. **Required Scopes:** `read:organization` (#7183, owner rule 2026-10-06 "every api/v1 door asks a scope"). A token without it gets `403 insufficient_permissions` ("Required scope: read:organization") before anything else is checked. Every sign-in token holds it, and so does a token a person makes by hand from this deploy on; a token made by hand before this deploy may not. A browser session is asked no scope. responses: '200': description: Core apps status retrieved successfully content: application/json: schema: type: object properties: apps: type: array items: "$ref": "#/components/schemas/CoreApp" total_count: type: integer description: Total number of core apps example: 6 enabled_count: type: integer description: Number of enabled core apps example: 3 _meta: "$ref": "#/components/schemas/ResponseMeta" '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" "/apps": get: tags: - Apps summary: List all apps (core and marketplace) description: | **Consolidated endpoint** that returns both core apps and marketplace apps in a single response. This is the recommended endpoint for mobile clients to build the app grid view. **Required Scopes:** `read:organization` (#7183, owner rule 2026-10-06 "every api/v1 door asks a scope"). A token without it gets `403 insufficient_permissions` ("Required scope: read:organization") before anything else is checked. Every sign-in token holds it, and so does a token a person makes by hand from this deploy on; a token made by hand before this deploy may not. A browser session is asked no scope. Core apps are fundamental platform features (Shifts & Scheduling, Time & Attendance, etc.) while marketplace apps are add-on features that can be enabled/disabled. **Features:** - Single API call instead of multiple requests - Unified sorting and filtering across all app types - Category-based organization - Type filtering (core, marketplace, or all) - Enabled/disabled filtering - **Mobile native app exclusion** via `exclude_mobile_native` parameter **Response includes:** - App icons (Font Awesome classes for mobile, with web_url fallback for custom SVG icons) - Launch URLs - Feature lists - Metadata - Category grouping **Icon Handling for Mobile:** All apps now return Font Awesome 5 icon classes in `icon.url` with `icon.type: "icon_class"`. For apps that have custom SVG icons, the original SVG path is available in `icon.web_url` for web clients that prefer to use the custom icons. **Mobile Native Apps:** Use `exclude_mobile_native=true` to exclude apps that are natively supported in mobile clients: - shift-marketplace - shifts_scheduling - time_attendance - leave_management - timesheets parameters: - name: type in: query required: false description: Filter apps by type (core, marketplace, or all) schema: type: string enum: - all - core - marketplace default: all example: all - name: category in: query required: false description: Filter apps by category (e.g., "HR Management", "Workforce Management") schema: type: string example: Workforce Management - name: enabled_only in: query required: false description: Whether to return only enabled apps schema: type: boolean default: true example: true - name: exclude_mobile_native in: query required: false description: | Exclude apps that are natively supported in mobile clients. When set to true, the following apps are excluded: - shift-marketplace - shifts_scheduling - time_attendance - leave_management - timesheets This is useful for mobile clients that already have native implementations of these core features and only need to display marketplace/web-based apps. schema: type: boolean default: false example: false - name: include_navigation in: query required: false description: | Opt into the **grouped, navigation-aware** response shape. Off by default so existing clients keep the flat legacy payload described above — this parameter changes the TOP-LEVEL shape of the response, it does not merely add a field. When `include_navigation=true`: * The response is split into `pinned_apps` (the apps pinned for this user) and `apps` (the remaining enabled apps), with `pinned_count` / `apps_count` / `total_count` / `categories`. `core_count`, `marketplace_count` and `enabled_count` are **not** returned in this mode. * Every app object carries `pinned`, `has_mobile_view`, `mobile_url` and a `navigation_items` array — the app's in-app navigation (its sidebar tabs / mobile TabBar), so a client can render an app's sub-pages without a second call per app. * `enabled_only` and `type` are **ignored**: pinned/unpinned lists come from the web sidebar's own role-aware source (`SidebarHelper#pinned_apps_for_user` / `#unpinned_enabled_apps`), which only ever yields enabled, user-accessible marketplace/core apps. `category` and `exclude_mobile_native` are still applied. * For mobile clients (native `User-Agent`), apps without a mobile-optimized view are dropped entirely, and each item's `path` is rewritten to its `/m/...` equivalent (see `navigation_items`). `navigation_items` is **role-aware and gated per app** — it contains only what the caller may actually open, so an item's absence is the authorization signal. Two examples of the gating, straight from the builders: * **Ideas** always returns `dashboard` (`/apps/ideas`) and `all_ideas` (`/apps/ideas/list`); `campaigns` appears unless the business explicitly disabled campaigns (`configuration["campaigns"] == false`); `review_queue` ("Reviews") appears **only** for members of a review panel — the workspace default panel or a campaign panel. Panel membership is the only grant: **admins get no bypass**, matching the web "My Review Queue" tab. * **Forms** always returns `my_submissions`; `approvals` appears only for reviewers (admin / manager / Forms App Admin) and carries a live `count` of pending approvals. * **Communications** returns a fixed four-item set with no gating: `dashboard` (`/apps/communications`), `feed` (`/apps/communications/feed`), `mail` (`/apps/communications/messages`) and `my_posts` (`/apps/communications/my-posts`). There is **no `notifications` item** — notifications are a platform surface the client owns and reads from `GET /api/v1/notifications`, not a Communications tab. * **Training** returns a fixed native-app bottom-tab set: the learner tabs `my_learning` ("My Learning", `/m/apps/training`), `catalog` ("Catalog", `/m/apps/training/catalog`) and `my_records` ("My Records", `/m/apps/training/certificates`) are always present; `my_team` ("My Team", `/m/apps/training/manager`) appears **only** for people-managers and admins/HR admins. The `my_learning` title is TENANT-RENAMEABLE — it is the Training app's `portal_title` setting, falling back to "My Learning" when the tenant has not set one, so it always matches the heading of the page the tab opens. Learning Paths is a course *type* inside Catalog, not a tab, so it is not a navigation item. * **Recognitions** always returns `dashboard` (`/recognition`), `feed` (`/recognition/feed`), `my_recognition` (`/recognition/my_recognition`) and `leaderboard` (`/recognition/leaderboard`), in that order. `programs` (`/recognition/programs`) appears unless the business turned award requests off (`enable_award_requests == false`); `awards` ("Award Cycles", `/recognition/award-cycles`) appears **only** when the business turned award cycles on (`enable_award_cycles == true`, off by default); `team` (`/recognition/manager`) appears **only** for recognition reviewers — business admins, Recognitions app admins, and anyone with direct reports. The app's admin surfaces (Analytics / Admin / Settings on the web rail) are deliberately not part of this mobile navigation, and `team` carries no badge count. * **Company Store** returns the native-app bottom-tab set: `dashboard` ("Dashboard", `/apps/company-store`), `catalog` ("Catalog", `/apps/company-store/catalog`), `orders` ("Orders", `/apps/company-store/orders`) and `balance` ("Points", `/apps/company-store/balance`) are always present, in that order; `approvals` ("Approvals", `/apps/company-store/manager/approvals`) appears **only** for redemption approvers — a member of the tenant's designated redemption-approver group, or a manager with direct reports when no such group is configured (a configured group supersedes the org chart, so a line manager outside it is not an approver; admins with direct reports are exempt from that supersession). A business admin with **no** direct reports is not an approver here — admins act on held orders through the admin orders queue instead. The rail's Cart tab (which appears only once a cart exists), its Team Budget action and its Admin / Settings dropdowns are not part of this mobile navigation, and `approvals` carries no badge count. * **Frontline Execution** returns a CURATED SUBSET of the app's web LHS sidebar — six tabs, each shown under the SAME visibility gating it has on the web rail: if the tab is hidden on web for this caller it is withheld here too. Two things gate a tab — its tenant SURFACE TOGGLE (so a disabled surface never leaves a tab that 403s) and, for the author-tier tabs, the caller's role. The tabs, in web order: * `my_day` ("My Day", `/apps/frontline-execution/my-day`) — every user; requires `enable_my_day`. * `requests` ("My requests", `/apps/frontline-execution/requests`) — every user; requires `enable_campaigns`. * `day_sheet` ("Day Sheet", `/apps/frontline-execution/day-sheet`) — the AUTHOR TIER (a business admin, the Frontline Execution app admin, or any manager); requires `enable_my_day`. * `reviews` ("Reviews", `/apps/frontline-execution/reviews`) — the author tier OR a completion **reviewer**; requires `enable_my_day`. * `campaigns` ("Campaigns", `/apps/frontline-execution/campaigns`) — the author tier; requires `enable_campaigns`. * `coverage` ("Coverage", `/apps/frontline-execution/coverage`) — the author tier; requires `enable_coverage`. `my_day` shows for every frontline user with no role gate (its endpoints — `GET /api/v1/frontline_execution/my_day` and `.../my_day/everything` — carry no author-tier gate either), so head office / district / regional users reach their own daily surface too. Paths are the web rail's own desktop `/apps/...` paths. No item carries a badge count. The rest of the web rail — Overview, Request queue, Calendar, People, Shared blockers, Analytics and the Admin zone (Settings / Import / Workforce sources) — is not part of this bar. * **Safety Hub** returns the per-persona navigation from the Safety Hub mobile prototype, in two zones. The **My** zone is every user's: `safety_hub_my_submitted` ("My Submitted", `/apps/safety-hub/submitted_by_me`) appears when either reporting module (incidents / observations) is on; `safety_hub_my_alerts` ("My Alerts", `/apps/safety-hub/alerts/my`) follows the `emergency_alerts_enabled` toggle; `safety_hub_my_permits` ("My Permits", `/apps/safety-hub/permits`, gated on `permits_enabled`) and `safety_hub_my_corrective_actions` ("My Corrective Actions", `/apps/safety-hub/corrective_actions`, gated on `incidents_enabled`) appear **only for non-managers** (a manager reaches the whole board from the Team zone, so emitting them too would be a second row to the same path); `safety_hub_knowledge_base` ("Knowledge Base", `/apps/safety-hub/knowledge_base`) is always present. The **Team** zone appears **only** for managers — a `manager_or_above?` user or the Safety Hub app admin — and holds `safety_hub_team_alerts` ("Team Alerts", `/apps/safety-hub/alerts`), `safety_hub_team_incidents` ("Team Incidents", `/apps/safety-hub/incidents`), `safety_hub_team_observations` ("Team Observations", `/apps/safety-hub/safety_observations`), `safety_hub_team_permits` ("Team Permits", `/apps/safety-hub/permits`, gated on `permits_enabled` — the whole permit board, the same index My Permits narrows for a non-manager) and `safety_hub_team_corrective_actions` ("Team Corrective Actions", `/apps/safety-hub/corrective_actions`), each gated by its module toggle. Keys are namespaced `safety_hub_*`; the app's compliance, certifications, toolbox-talks, campaigns and admin surfaces are not part of this navigation, and no item carries a badge count. * **Service Desk** returns the per-persona bottom bar from the Service Desk mobile prototype. The persona is the caller's Service Desk role: **admin** (business admin or Service Desk app admin), **agent** (member of an active support team, or granted agent rights in Settings → Agents), **manager** (help desk manager without agent rights) or **member** (everyone else). * **member** — `service_desk_my_requests` ("My Requests"), `service_desk_grievances` ("Grievances", `/apps/service-desk/grievances`) and `service_desk_knowledge_base` ("Knowledge", `/apps/service-desk/knowledge-base`). * **manager** — `service_desk_my_requests`, `service_desk_access_requests` ("Access", `/apps/service-desk/access-requests`), `service_desk_grievances` and `service_desk_knowledge_base`. * **agent** and **admin** — `service_desk_agent_dashboard` ("Dashboard", `/apps/service-desk/agent_dashboard`), `service_desk_tickets` ("Tickets" — an agent's own workbench `/apps/service-desk/agent_tickets`; for an admin the tenant-wide `/apps/service-desk/tickets`), `service_desk_knowledge_base`, and `service_desk_more` ("More"). `service_desk_more` has no `path`; its `actions` list the enabled overflow modules — `service_desk_problems` (`/apps/service-desk/problems`), `service_desk_changes` (`/apps/service-desk/changes`), `service_desk_access_requests` and `service_desk_grievances` — and each action carries its own `key`. When only one of them is enabled it is returned as a normal item instead of `service_desk_more`; when none is, there is no More item. `service_desk_my_requests` is `/m/apps/service-desk` for a mobile caller and `/apps/service-desk/my_requests` otherwise. Knowledge follows the tenant's `knowledge_base_enabled` setting; Access, Problems, Changes and Grievances follow their Service Desk modules. `service_desk_grievances` is the app's door to file a grievance (GET /service_desk/service_catalog never lists that type); render it from GET /service_desk/grievances. Keys are namespaced `service_desk_*`. Analytics, Settings and CMDB are not part of this navigation, and no item carries a badge count. * **Sites** returns the bar from the Sites mobile prototype — the web rail's reader rows, in its order, each under the SAME gate the web rail applies (asked of the web's own Sites predicates, so the two cannot disagree about a person): * `sites_dashboard` ("Dashboard", `/apps/sites`, icon `fas fa-gauge`) — only when the Dashboard has work for the caller: a business admin, a Sites app admin, someone who may create sites or owns / edits one, a page reviewer, or the owner of a page. A member who only reads has no Dashboard (on the web they land on All sites). * `sites_all_sites` ("All sites", `/apps/sites/list`, `fas fa-globe`) — always. * `sites_recent` ("Recent", `/apps/sites/recent`, `fas fa-clock-rotate-left`) — while the tenant records page views (`enable_analytics`, on by default). * `sites_saved` ("Saved & following", `/apps/sites/bookmarks`, `fas fa-bookmark`) — always, with the same label for every role. `count` is the number of must-read pages waiting on the caller's confirmation; while it is above 0 the path opens on that list (`/apps/sites/bookmarks?tab=confirm`). `tabs` is the screen's segmented control, the web's tabs in order — `{ key, title }`, `count` on `confirm` — each key naming its list: `bookmarks` → `GET /sites/bookmarks`, `following` → `GET /sites/following`, `watching` → `GET /sites/watching`, `confirm` → `GET /sites/to_confirm`. Following and Watching are there only while the tenant's site follows are on. * `sites_approvals` ("Approvals", `/apps/sites/reviews`, `fas fa-clipboard-check`) — only while page approvals are on (`enable_content_review`) and the caller is a business admin, a Sites app admin, an owner or editor of a site, or someone a page approval was sent to or sent by. `count` is what waits on the caller (requests to decide, their requests sent back, and their approved pages ready to publish); while it is above 0 the path opens on that list (`/apps/sites/reviews?filter=waiting`). For a mobile caller the paths are the phone pages: `sites_dashboard` and `sites_all_sites` → `/m/apps/sites` (the phone sites list, which draws the Dashboard's sections above it), `sites_recent` → `/m/apps/sites/recent`, `sites_saved` → `/m/apps/sites/bookmarks` (`?tab=confirm` as above). `sites_approvals` has no phone page and keeps its desktop path — draw it natively by `key`. Keys are namespaced `sites_*`. The web rail's "Your sites", Site resources and Admin groups are not part of this navigation. Titles are written in the caller's language, as for Service Desk. * **Meal Compliance** returns the per-persona bar from the Meal Compliance mobile prototype, each item under the SAME gate the web rail applies (asked of the web's own Meal Compliance predicates): * `meal_compliance_dashboard` ("Dashboard", `/apps/meal-compliance`, icon `fas fa-gauge-high`) — managers and admins: a business admin, a Meal Compliance app admin, an HR admin, or a manager of direct reports (a manager role, or anyone people report to). * `meal_compliance_my_breaks` ("My Breaks", `/apps/meal-compliance/my-breaks`, `fas fa-mug-hot`) — always: the caller's own waiver status and break history. * `meal_compliance_waivers` ("Waivers", `/apps/meal-compliance/waivers`, `fas fa-file-signature`) — the same people as Dashboard. * `meal_compliance_break_compliance` ("Break Compliance", `/apps/meal-compliance/break-compliance`, `fas fa-clipboard-check`) — admins only: a business admin, a Meal Compliance app admin or an HR admin. So an employee gets My Breaks; a manager Dashboard · My Breaks · Waivers; an admin all four, in that order. The paths are the desktop pages for every caller, mobile included — draw each screen natively by `key` (the desktop My Breaks page sends a phone to `/m/apps/meal-compliance` itself). An employee's single item is kept, not collapsed into the tile. Keys are namespaced `meal_compliance_*`. The web rail's Settings is not part of this navigation, and no item carries a badge count. Titles are written in the caller's language, as for Service Desk. Every item also carries `can_create_waiver` (boolean, the same value on each item): whether the caller may start a New Waiver, which the prototype offers as the (+) button on Dashboard and Waivers. It is the web's New Waiver rule — a business admin, a Meal Compliance app admin, an HR admin or a manager of direct reports — and the token must hold `write:meal_compliance`, so a read-only token answers `false` while the items stay the same. It matches `permissions.can_create_waiver` on `GET /meal_compliance/dashboard` and `GET /meal_compliance/waivers`. * **SOP Hub** returns the per-persona bar from the SOP Hub mobile prototype, each item under the SAME gate the web rail applies: * `sop_hub_dashboard` ("Dashboard", `/apps/sop-hub`, icon `fas fa-gauge`) — always. Render it from `GET /sop_hub/dashboard`. * `sop_hub_my_sops` ("My SOPs", `/apps/sop-hub/completions/my_pending`, `fas fa-clipboard-check`) — always: the caller's own SOPs, Pending (`GET /sop_hub/completions/my_pending`) and History (`GET /sop_hub/completions/my_history`). * `sop_hub_reports` ("Reports", `/apps/sop-hub/completions/report`, `fas fa-clipboard-list`) — SOP Hub authors only: an HR admin, a business admin, a SOP Hub app admin, or a SOP Hub admin limited to places and departments — exactly the people `GET /sop_hub/reports/compliance`, `GET /sop_hub/completions` and `GET /sop_hub/activity_logs` admit, so the tab never opens on a 403. So an employee (and a manager who is not a SOP Hub author) gets Dashboard · My SOPs; an admin all three, in that order. For a mobile caller `sop_hub_dashboard` is `/m/apps/sop-hub` and `sop_hub_my_sops` is `/m/apps/sop-hub/my-pending`; `sop_hub_reports` has no phone page and keeps its desktop path — draw it natively by `key`. Keys are namespaced `sop_hub_*`. The web rail's Browse SOPs, Manage, Templates, Manuals and Settings are not part of this navigation, and no item carries a badge count. Titles are written in the caller's language, as for Service Desk. Gotchas: * An app can legitimately return `navigation_items: []` — either it exposes no sub-navigation, or (on mobile) every tab it has was dropped for lacking a real `/m/` route. Build the tile to open `mobile_url` / `url` in that case. * Single-child collapse (mobile only): when an app would return exactly ONE navigable item that belongs to its own mobile route, the item is removed and `mobile_url` is repointed at it, so the tile opens that page directly instead of a one-row submenu. * `navigation_items` is best-effort per app: if the underlying tab builder raises, that app returns `[]` rather than failing the request. * An item's `title` (and an action's `title`) is display text, not an identifier — clients branch on `key`. For **Service Desk**, **Sites** and **Meal Compliance** the titles are written in the language the client asks for: the `locale` query parameter, else `Accept-Language` (first supported tag by q-value; `nb`/`nn` read as `no`, `iw` as `he`), else the caller's own profile language, else the tenant's default, else English — whether or not the tenant translates its web pages. The response then carries `Vary: Accept-Language`. Other apps' titles are English today. schema: type: boolean default: false example: true - name: locale in: query required: false description: | The language the client's own interface is in (e.g. `fr`, `pt-BR`). Takes precedence over `Accept-Language` for the `title`s written in the caller's language (see `include_navigation`). An unsupported code is ignored. schema: type: string example: fr responses: '200': description: Apps retrieved successfully content: application/json: schema: type: object properties: apps: type: array description: | Array of apps (both core and marketplace). With `include_navigation=true` this holds only the **unpinned** enabled apps (the pinned ones move to `pinned_apps`), and every entry carries `pinned`, `has_mobile_view`, `mobile_url` and `navigation_items`. items: "$ref": "#/components/schemas/ConsolidatedApp" pinned_apps: type: array description: | The apps pinned for this user, in the same order the web sidebar pins them. **Only present when `include_navigation=true`.** Same item schema as `apps`, with `pinned: true`. items: "$ref": "#/components/schemas/ConsolidatedApp" pinned_count: type: integer description: Number of entries in `pinned_apps`. Only present when `include_navigation=true`. example: 4 apps_count: type: integer description: Number of entries in `apps` (unpinned). Only present when `include_navigation=true`. example: 18 total_count: type: integer description: | Total number of apps returned. With `include_navigation=true` this is `pinned_count + apps_count`. example: 12 unread_notification_count: "$ref": "#/components/schemas/UnreadNotificationCount" core_count: type: integer description: Number of core apps in response example: 6 marketplace_count: type: integer description: Number of marketplace apps in response example: 6 enabled_count: type: integer description: Number of enabled apps example: 9 categories: type: array description: List of unique categories across all apps items: type: string example: - HR Management - Workforce Management - Analytics _meta: "$ref": "#/components/schemas/ResponseMeta" examples: default: summary: All apps (default) value: apps: - id: shifts_scheduling slug: shifts_scheduling name: Shifts & Scheduling description: Complete shift scheduling and management system type: core category: Workforce Management enabled: true icon: url: fas fa-calendar-alt type: icon_class url: "/shifts" sort_order: 1 - id: 123 slug: employee-performance-management name: Employee Performance Management description: Comprehensive performance management system type: marketplace category: performance enabled: true icon: url: fas fa-chart-line type: icon_class web_url: "/assets/icons/employee-performance-management.svg" url: "/apps/employee-performance-management" sort_order: 2 total_count: 12 core_count: 6 marketplace_count: 6 enabled_count: 10 categories: - HR Management - Workforce Management - performance core_only: summary: Core apps only value: apps: - id: shifts_scheduling slug: shifts_scheduling name: Shifts & Scheduling type: core enabled: true icon: url: fas fa-calendar-alt type: icon_class total_count: 6 core_count: 6 marketplace_count: 0 enabled_count: 6 marketplace_only: summary: Marketplace apps only value: apps: - id: 123 slug: employee-performance-management name: Employee Performance Management type: marketplace enabled: true icon: url: fas fa-chart-line type: icon_class web_url: "/assets/icons/employee-performance-management.svg" total_count: 6 core_count: 0 marketplace_count: 6 enabled_count: 4 exclude_mobile_native: summary: Exclude mobile native apps description: Response when exclude_mobile_native=true, excluding shifts_scheduling, time_attendance, leave_management, timesheets value: apps: - id: skills_certifications slug: skills_certifications name: Skills & Certifications type: core category: HR Management enabled: true icon: url: fas fa-graduation-cap type: icon_class - id: compensation_management slug: compensation_management name: Compensation Management type: core category: HR Management enabled: true icon: url: fas fa-dollar-sign type: icon_class - id: 123 slug: employee-performance-management name: Employee Performance Management type: marketplace enabled: true icon: url: fas fa-chart-line type: icon_class web_url: "/assets/icons/employee-performance-management.svg" total_count: 8 core_count: 2 marketplace_count: 6 enabled_count: 7 categories: - HR Management - performance include_navigation: summary: Grouped format with per-app navigation (include_navigation=true) description: | Pinned/unpinned grouping with role-aware `navigation_items`. This Ideas entry is what a NON-reviewer receives — the `review_queue` ("Reviews") item is absent because the caller belongs to no review panel. value: pinned_apps: - id: 141 slug: ideas name: Ideas type: marketplace category: Collaboration enabled: true pinned: true icon: url: fas fa-lightbulb type: icon_class url: "/apps/ideas" has_mobile_view: true mobile_url: "/m/apps/ideas" navigation_items: - key: dashboard title: Dashboard icon: fas fa-gauge path: "/apps/ideas" - key: all_ideas title: Ideas icon: fas fa-lightbulb path: "/apps/ideas/list" - key: campaigns title: Campaigns icon: fas fa-bullhorn path: "/apps/ideas/campaigns" apps: - id: 152 slug: wikis name: Wikis type: marketplace category: Knowledge enabled: true pinned: false icon: url: fas fa-book type: icon_class url: "/apps/wikis" has_mobile_view: true mobile_url: "/m/apps/wikis" navigation_items: - key: dashboard title: Dashboard icon: fas fa-gauge path: "/apps/wikis" - key: all_wikis title: All wikis icon: fas fa-list-ul path: "/apps/wikis/browse" - id: 168 slug: safety-hub name: Safety Hub type: marketplace category: workplace-ops enabled: true pinned: false icon: url: fas fa-shield-halved type: icon_class url: "/apps/safety-hub" has_mobile_view: true mobile_url: "/m/apps/safety-hub" navigation_items: - key: safety_hub_my_submitted title: My Submitted icon: fas fa-clipboard-check path: "/apps/safety-hub/submitted_by_me" - key: safety_hub_my_alerts title: My Alerts icon: fas fa-bullhorn path: "/apps/safety-hub/alerts/my" - key: safety_hub_knowledge_base title: Knowledge Base icon: fas fa-book-open path: "/apps/safety-hub/knowledge_base" - key: safety_hub_team_alerts title: Team Alerts icon: fas fa-bullhorn path: "/apps/safety-hub/alerts" - key: safety_hub_team_incidents title: Team Incidents icon: fas fa-triangle-exclamation path: "/apps/safety-hub/incidents" - key: safety_hub_team_observations title: Team Observations icon: fas fa-eye path: "/apps/safety-hub/safety_observations" - key: safety_hub_team_permits title: Team Permits icon: far fa-file-lines path: "/apps/safety-hub/permits" - key: safety_hub_team_corrective_actions title: Team Corrective Actions icon: fas fa-clipboard-check path: "/apps/safety-hub/corrective_actions" - id: 107 slug: sites name: Sites type: core category: productivity-utility enabled: true pinned: false icon: url: fas fa-globe type: icon_class url: "/apps/sites" has_mobile_view: true mobile_url: "/m/apps/sites" navigation_items: - key: sites_dashboard title: Dashboard icon: fas fa-gauge path: "/apps/sites" - key: sites_all_sites title: All sites icon: fas fa-globe path: "/apps/sites/list" - key: sites_recent title: Recent icon: fas fa-clock-rotate-left path: "/apps/sites/recent" - key: sites_saved title: Saved & following icon: fas fa-bookmark path: "/apps/sites/bookmarks?tab=confirm" count: 2 tabs: - key: bookmarks title: Bookmarks - key: following title: Following - key: watching title: Watching - key: confirm title: To confirm count: 2 - key: sites_approvals title: Approvals icon: fas fa-clipboard-check path: "/apps/sites/reviews?filter=waiting" count: 1 total_count: 4 pinned_count: 1 apps_count: 3 categories: - Collaboration - Knowledge - productivity-utility - workplace-ops unread_notification_count: 3 '401': "$ref": "#/components/responses/Unauthorized" '403': "$ref": "#/components/responses/Forbidden" '422': description: Business context not available content: application/json: schema: type: object properties: error: type: object properties: code: type: string example: validation_failed message: type: string example: No business context available apps: type: array items: {} example: [] total_count: type: integer example: 0 "/shifts": get: tags: - Shifts summary: List shifts description: | Returns shifts with flexible filtering and parameter-based querying. Supports: - User-specific shifts (user_id=current for authenticated user) - Open shifts available for claiming (type=open) - Current active shifts (type=current) - Period-based filtering (today, week, upcoming, past) - **NEW: Marketplace filters** - `marketplace_available`: Shifts available in the marketplace that the user can claim - `marketplace_claimed`: Shifts the user has claimed from the marketplace - `marketplace_listed`: Shifts the user has listed in the marketplace parameters: - name: type in: query description: | Type of shifts to retrieve. **Standard Types:** - `assigned`: User's assigned shifts (default) - `open`: Open shifts available for claiming - `current`: Currently active shifts - `all`: All shifts (admin/manager view) **Marketplace Types:** - `marketplace_available`: Shifts in marketplace available for claiming (excludes user's own shifts) - `marketplace_claimed`: Shifts user has claimed from marketplace (identified by marketplace_pickup flag) - `marketplace_listed`: Shifts user has listed for others to claim schema: type: string enum: - assigned - open - current - all - marketplace_available - marketplace_claimed - marketplace_listed default: assigned - name: period in: query description: | Time period filter, evaluated against the shift's start/end time. `week` uses the TENANT'S configured week start (Settings → business hours), not a fixed Monday, so it matches what the web schedule shows. On the default shift list, explicit `start_date` / `end_date` / `date` take precedence: when any of them is sent, `period` does not narrow the result and only sets the sort direction (`past` = newest first). Supported with the default shift list, `type=assigned`, `type=marketplace_claimed` and `type=marketplace_listed`. Combining it with `type=open`, `type=current` or `type=marketplace_available` returns 400 `period_status_filter_not_supported_for_type` — those views already return a fixed set (claimable upcoming shifts, or the shifts in progress right now) and silently ignoring the filter would ship a list the caller believes was narrowed. schema: type: string enum: - current - today - week - upcoming - past - name: user_id in: query description: User ID or 'current' for authenticated user's shifts schema: oneOf: - type: integer - type: string enum: - current - name: location_id in: query description: | Filter by specific location ID. For multiple locations, use location_ids[] instead. Also accepts comma-separated values (e.g., location_id=1,2,3) for backwards compatibility. schema: type: string example: '1' - name: location_ids[] in: query description: "Filter by multiple location IDs. Use this to fetch shifts across all locations \nassigned to a user. Can be passed as an array (location_ids[]=1&location_ids[]=2) \nor comma-separated (location_ids=1,2,3).\n" schema: type: array items: type: integer style: form explode: true example: - 1 - 2 - 3 - name: scope in: query description: | Narrow the list to shifts belonging to the CALLING user's own locations, departments, or teams. Takes no ids — the scope is resolved server-side from the authenticated user, so a client never has to hold a synced copy of their memberships. A shift is in scope when EITHER (a) the shift carries one of the USER'S OWN ids for the dimension — it is at one of their locations, or it (or its SCHEDULE) is for one of their teams / departments, OR (b) the shift carries THAT DIMENSION AT ALL, and somebody assigned to it is one of the user's people. Both halves matter: (a) alone misses a shift your employee picked up at another site; (b) alone misses an UNASSIGNED shift at your own site, which has nobody on it to make it yours. The dimension gate on (b) is what makes the scope name mean what it says. `scope=team` returns TEAM shifts only: a shift grouped by LOCATION, or an ad-hoc shift with no grouping at all, is not returned just because a teammate happens to be rostered on it. Likewise `scope=department` returns only shifts that carry a department. The gate is a no-op for `scope=location`, where no shift can lack a location. `scope=team` means CUSTOM scheduling teams. The three group types each answer to their own scope name: `location` groups (auto-created per site) to `scope=location`, `department` groups (auto-created from an org-chart department) to `scope=department`, and `custom` groups to `scope=team`. Note a team built by hand and filtered to a department is stored as `custom`, so it answers to `scope=team`. Composes with `location_id` / `start_date` etc. rather than replacing them — every filter narrows. A user whose scope resolves to nothing receives an empty list, never the whole business. AVAILABLE TO EVERY ROLE, INCLUDING A PLAIN EMPLOYEE (2026-09-02). On the DEFAULT list a caller who is not entitled to a business-wide read normally receives only their own assigned shifts; passing a resolved `scope` lifts that to their own unit — their colleagues' shifts, plus unassigned shifts at the unit, plus a colleague's shift worked at another site (half (b)). This is parity with the web Team Calendar, which has served an employee the same roster since 2026-07-09. The reach is the UNIT and never the tenant: the resolver bounds an employee's `location` dimension to their own assigned locations, and `team` / `department` to memberships they actually hold. TWO THINGS IT DOES NOT LIFT. * A token carrying only `read:own_shifts` is unaffected — it still receives own-assignment rows with or without `scope`. The widening requires `read:shifts` / `write:shifts` / `admin`, or a session, exactly as a business-wide read does. * `user_id=` is still refused with 403. Reading your unit's week is not the same as reading one named colleague's schedule. Team and department are read from the shift's SCHEDULE as well as the shift's own columns, because tenants attach them to the schedule and only some of it is copied down. `scope=department` additionally matches department-flavoured scheduling groups, which is the only way an ORG-CHART department resolves at all — neither shifts nor schedules carry a column for one. Supported with the DEFAULT shift list and `type=open` only. Combining it with `type=assigned|current|marketplace_*`, or with `user_id=current`, returns 400 `scope_not_supported_for_type` — those views are already narrowed to the caller, and silently ignoring the filter would return a response whose `meta.user_scope` named a scope that was never applied. Responses include `meta.user_scope` describing what the scope resolved to. A caller that resolves to no locations, teams or departments receives an EMPTY list — the filter fails closed. schema: type: string enum: - location - department - team example: location - name: status in: query description: | Filter by shift status. Supported with the same types as `period` (see above); `type=open`, `type=current` and `type=marketplace_available` return 400 `period_status_filter_not_supported_for_type`. On `type=marketplace_listed` this filters the LISTING status, not the shift status. NOTE: `open` is NOT a valid shift status — the model permits only scheduled / completed / cancelled / late_reported / absence_reported, so `?status=open` matches zero rows. Use `?type=open` to list shifts available for claiming. schema: type: string enum: - scheduled - completed - cancelled - late_reported - absence_reported - name: date in: query description: Filter shifts by specific date (YYYY-MM-DD) schema: type: string format: date - name: start_date in: query description: 'Lower bound on the shift''s START date (inclusive). ' schema: type: string format: date - name: end_date in: query description: | Upper bound on the shift's START date (inclusive) — i.e. `start_date` and `end_date` together select the shifts that BEGIN inside the window, which is what the web date filter does. This bound was previously applied to `end_time`, which silently excluded every open-ended (ad-hoc) shift — those have no end time — and every overnight shift that began inside the window but finished after it. schema: type: string format: date - name: include in: query description: | Additional data to include. Accepts a comma-separated string (`include=a,b`) or repeated bracket notation (`include[]=a&include[]=b`). `user_scope` adds a `meta.user_scope` object listing the caller's own locations, departments and teams. It is included automatically whenever `scope` is passed; request it explicitly to read the memberships WITHOUT filtering by them. `user_scope.departments` names the caller's DEPARTMENT TEAMS — scheduling groups of `group_type: "department"`, each rendered as `{ id, name, type: "department_team", group_type, organizational_department_id }`. These are the same objects a matched shift echoes in its own `scheduling_group`, so a client can reconcile the two by id. Use `organizational_department_id` to reach the org-chart department the team was derived from. CAVEAT: `scope=department` ALSO matches shifts on `shifts.location_department_id` / `schedule_locations.location_department_id`, and those matches have no entry in `user_scope.departments` — a shift can therefore be returned with no meta row explaining it, and a caller whose only department signal is a LocationDepartment sees `departments: []` alongside a non-empty shift list. Prior to 2026-08-27 this array carried LocationDepartment and OrganizationalDepartment records instead; it was changed so the meta names the same objects the items do. Costs ~13 extra queries (measured), and is paid on EVERY page, so it is off by default for clients that page this endpoint in a loop. `scope_users` adds `meta.user_scope.user_ids` — the people the scope resolved to, i.e. the users who share the requested dimension with the caller. It answers "who are my colleagues for this scope", which is NOT the same question as `teammates`: teammates the people assigned to each returned shift user_ids everyone in my location / team / department, whether or not they have a shift in this response So a shift can be returned for a person who is NOT in `user_ids` (it is at your location, but they are not one of your people), and `user_ids` can name someone with no shift in the response at all. Costs no extra queries on a `?scope=`d request — the filter already resolved that list to build its roster half. IDS ONLY, deliberately: hydrating names and avatars costs roughly two queries per user, so fetch the people themselves from `/api/v1/users` when you need more than an id. The list names the caller's colleagues when the RESPONSE ROWS are roster-wide, and is bounded to the caller's own id otherwise (`counts.users` then 1, or 0 when the scope resolved to nothing). Rows are roster-wide for a business-wide read, and — since 2026-09-02 — for any role that passed a resolved `scope` on a credential permitted to read shifts. So the bound still applies to: * a caller on the DEFAULT list with no `scope`, whose rows are their own assignments, and * a caller of ANY role, manager and admin included, whose token carries only `read:own_shifts`. Unchanged property: the bound never depends on `type`. One resolver is memoized per request and shared by every handler, so `user_ids` is a function of the caller's entitlement and of whether a `scope` was passed — not of which `type` view ran. That matters for `type=open`, whose items are unassigned shifts rather than the caller's own. IT IS THE ROSTER, NOT AN INDEX OF ASSIGNEES. The list is "my people" — the members of the resolved unit. A shift returned by half (a) may be worked by somebody who does NOT belong to that unit (an outsider covering a shift at your site); their shift is in `items` and their id is deliberately NOT here. Read an assignee from the shift row or `include=teammates`, never by assuming this list covers every person you will encounter. Capped at 50 like the other `user_scope` arrays, with `counts.users` always EXACT and the shared `truncated` flag set when the array was cut. For an ADMIN on `scope=location` the list is tenant-sized, because an admin's location scope is every location in the business — read `counts.users` rather than the array length. For `scope=team` and `scope=department` it is membership-only and never role-widened. With no `scope`, `user_ids` is empty by definition. `attendance` REQUIRES `format=detailed` ON THIS ENDPOINT — verified over HTTP 2026-09-02. Each item's `attendance_records` array is emitted only by the detailed serializer, and this list defaults to `format=standard`, so `include=attendance` on its own answers 200 with no attendance data and nothing in the response to say why — note the example value below includes `attendance`, so following it literally is what surfaces this. Pass `format=detailed&include=attendance`. `GET /api/v1/shifts/{id}` needs no such pairing — its `format` already defaults to `detailed`. `teammates` and `notes` are unaffected: they render at every format. schema: type: string example: teammates,notes,attendance,user_scope,scope_users - name: format in: query description: Response detail level schema: type: string enum: - minimal - standard - detailed default: standard - name: page in: query schema: type: integer default: 1 - name: per_page in: query schema: type: integer default: 25 maximum: 100 responses: '200': description: List of shifts headers: X-Total-Count: schema: type: integer X-Total-Pages: schema: type: integer X-Current-Page: schema: type: integer X-Per-Page: schema: type: integer content: application/json: schema: allOf: - "$ref": "#/components/schemas/CollectionEnvelope" - type: object properties: items: type: array items: type: object properties: id: type: integer example: 123 managed_by: type: string nullable: true example: UKG description: 'The workforce management system of record that owns this shift ("Managed in UKG"), or null. A managed shift is read-only here: coverage requests and edits answer 422 `externally_managed`.' name: type: string example: Morning Shift description: type: string nullable: true start_time: type: string format: date-time example: '2025-01-27T09:00:00Z' end_time: type: string format: date-time example: '2025-01-27T17:00:00Z' formatted_date: type: string description: Human-readable date format example: Monday, Jan 27 formatted_time: type: string description: Human-readable time range example: 9:00 AM - 5:00 PM status: type: string enum: - scheduled - completed - cancelled - open example: scheduled urgent: type: boolean description: Whether this shift is marked as urgent example: false needs_coverage: type: boolean description: Whether this shift needs coverage example: false can_list_for_coverage: type: boolean description: Whether the current user can list this shift for coverage in the marketplace example: true is_already_listed: type: boolean description: Whether this shift is already listed in the marketplace by the current user example: false required_users: type: integer description: Number of users required for this shift location: type: object properties: id: type: integer example: 1 name: type: string example: Downtown Store address: type: string nullable: true phone: type: string nullable: true users: type: array items: "$ref": "#/components/schemas/User" available_actions: type: array description: Actions available to the current user for this shift items: type: string enum: - view_details - request_coverage - report_lateness - view_teammates - claim example: - view_details - request_coverage - view_teammates teammates: type: array description: Other users assigned to this shift (when include=teammates) nullable: true items: type: object properties: id: type: integer description: User ID name: type: string description: User full name job_title: type: string nullable: true description: User's job title/role profile_photo_url: type: string nullable: true description: Full-size profile photo URL (200x200) or avatar placeholder profile_photo_thumbnail_url: type: string nullable: true description: Thumbnail profile photo URL (40x40) optimized for list views listed_by: type: object nullable: true description: User who listed this shift in the marketplace (teammate format, present for marketplace shifts) properties: id: type: integer description: User ID name: type: string description: User full name job_title: type: string nullable: true description: User's job title/role profile_photo_url: type: string nullable: true description: Full-size profile photo URL (200x200) or avatar placeholder profile_photo_thumbnail_url: type: string nullable: true description: Thumbnail profile photo URL (40x40) optimized for list views picked_by: type: object nullable: true description: User who claimed/picked up this shift from the marketplace (teammate format, present when shift was claimed) properties: id: type: integer description: User ID name: type: string description: User full name job_title: type: string nullable: true description: User's job title/role profile_photo_url: type: string nullable: true description: Full-size profile photo URL (200x200) or avatar placeholder profile_photo_thumbnail_url: type: string nullable: true description: Thumbnail profile photo URL (40x40) optimized for list views marketplace_info: type: object nullable: true description: Marketplace listing information (present when shift has marketplace listing) properties: has_listing: type: boolean description: Whether this shift has an active marketplace listing example: true listing_id: type: integer description: ID of the marketplace listing example: 880 listing_status: type: string enum: - open - filled - closed - cancelled description: Current status of the marketplace listing example: open lister_status: type: string enum: - open - filled - traded - closed - cancelled description: 'Present only when the listing is the caller''s own. The status as its lister reads it: listing_status, except a listing filled by an accepted trade is traded (filled = picked up). Switch on this key, never on lister_status_label.' example: traded lister_status_label: type: string description: Present only when the listing is the caller's own. The word the web and phone pages show the lister (Available, Covered, Traded, Closed, Cancelled), in the language the client asks for (the locale param, else Accept-Language, else the person's own language). example: Traded listing_type: type: string enum: - pickup - trade_only - both description: Type of marketplace listing - pickup (direct claim), trade_only (requires application/trade), or both (accepts either) example: pickup price: type: number format: float description: Price offered for the shift example: 0.01 currency: type: string description: Currency code (e.g., USD) example: USD listed_by: type: integer description: User ID of the person who listed the shift (legacy field, use listed_by object instead) example: 1487 listed_at: type: string format: date-time description: When the shift was listed in the marketplace example: '2025-12-01T10:05:00Z' notes: type: string nullable: true description: Shift notes (when include=notes) created_at: type: string format: date-time updated_at: type: string format: date-time meta: allOf: - "$ref": "#/components/schemas/CollectionPaginationMeta" - type: object properties: current_time: type: string format: date-time description: "`type=current` only: the server time the window was measured from." current_shift: allOf: - type: object properties: id: type: integer example: 123 managed_by: type: string nullable: true example: UKG description: 'The workforce management system of record that owns this shift ("Managed in UKG"), or null. A managed shift is read-only here: coverage requests and edits answer 422 `externally_managed`.' name: type: string example: Morning Shift description: type: string nullable: true start_time: type: string format: date-time example: '2025-01-27T09:00:00Z' end_time: type: string format: date-time example: '2025-01-27T17:00:00Z' formatted_date: type: string description: Human-readable date format example: Monday, Jan 27 formatted_time: type: string description: Human-readable time range example: 9:00 AM - 5:00 PM status: type: string enum: - scheduled - completed - cancelled - open example: scheduled urgent: type: boolean description: Whether this shift is marked as urgent example: false needs_coverage: type: boolean description: Whether this shift needs coverage example: false can_list_for_coverage: type: boolean description: Whether the current user can list this shift for coverage in the marketplace example: true is_already_listed: type: boolean description: Whether this shift is already listed in the marketplace by the current user example: false required_users: type: integer description: Number of users required for this shift location: type: object properties: id: type: integer example: 1 name: type: string example: Downtown Store address: type: string nullable: true phone: type: string nullable: true users: type: array items: "$ref": "#/components/schemas/User" available_actions: type: array description: Actions available to the current user for this shift items: type: string enum: - view_details - request_coverage - report_lateness - view_teammates - claim example: - view_details - request_coverage - view_teammates teammates: type: array description: Other users assigned to this shift (when include=teammates) nullable: true items: type: object properties: id: type: integer description: User ID name: type: string description: User full name job_title: type: string nullable: true description: User's job title/role profile_photo_url: type: string nullable: true description: Full-size profile photo URL (200x200) or avatar placeholder profile_photo_thumbnail_url: type: string nullable: true description: Thumbnail profile photo URL (40x40) optimized for list views listed_by: type: object nullable: true description: User who listed this shift in the marketplace (teammate format, present for marketplace shifts) properties: id: type: integer description: User ID name: type: string description: User full name job_title: type: string nullable: true description: User's job title/role profile_photo_url: type: string nullable: true description: Full-size profile photo URL (200x200) or avatar placeholder profile_photo_thumbnail_url: type: string nullable: true description: Thumbnail profile photo URL (40x40) optimized for list views picked_by: type: object nullable: true description: User who claimed/picked up this shift from the marketplace (teammate format, present when shift was claimed) properties: id: type: integer description: User ID name: type: string description: User full name job_title: type: string nullable: true description: User's job title/role profile_photo_url: type: string nullable: true description: Full-size profile photo URL (200x200) or avatar placeholder profile_photo_thumbnail_url: type: string nullable: true description: Thumbnail profile photo URL (40x40) optimized for list views marketplace_info: type: object nullable: true description: Marketplace listing information (present when shift has marketplace listing) properties: has_listing: type: boolean description: Whether this shift has an active marketplace listing example: true listing_id: type: integer description: ID of the marketplace listing example: 880 listing_status: type: string enum: - open - filled - closed - cancelled description: Current status of the marketplace listing example: open lister_status: type: string enum: - open - filled - traded - closed - cancelled description: 'Present only when the listing is the caller''s own. The status as its lister reads it: listing_status, except a listing filled by an accepted trade is traded (filled = picked up). Switch on this key, never on lister_status_label.' example: traded lister_status_label: type: string description: Present only when the listing is the caller's own. The word the web and phone pages show the lister (Available, Covered, Traded, Closed, Cancelled), in the language the client asks for (the locale param, else Accept-Language, else the person's own language). example: Traded listing_type: type: string enum: - pickup - trade_only - both description: Type of marketplace listing - pickup (direct claim), trade_only (requires application/trade), or both (accepts either) example: pickup price: type: number format: float description: Price offered for the shift example: 0.01 currency: type: string description: Currency code (e.g., USD) example: USD listed_by: type: integer description: User ID of the person who listed the shift (legacy field, use listed_by object instead) example: 1487 listed_at: type: string format: date-time description: When the shift was listed in the marketplace example: '2025-12-01T10:05:00Z' notes: type: string nullable: true description: Shift notes (when include=notes) created_at: type: string format: date-time updated_at: type: string format: date-time nullable: true user_timezone: type: string example: America/New_York type: type: string example: open_shifts day_notes: type: array description: | Your own shifts only (`type=assigned` or `user_id=current`, not another person's): the schedule notes for the next 14 days of published schedules at your locations or with your shifts, soonest first — the same "Schedule notes" My Shifts shows on the web. items: type: object properties: id: type: integer date: type: string format: date example: '2025-01-28' body: type: string example: Quarterly department meeting at 2 PM schedule_id: type: integer schedule_name: type: string nullable: true examples: my_shifts: summary: My assigned shifts value: items: - id: 123 name: Morning Shift date: Monday, Jan 27 start_time: '2025-01-27T09:00:00Z' end_time: '2025-01-27T17:00:00Z' location: id: 1 name: Downtown Store status: scheduled urgent: false needs_coverage: false available_actions: - view_details - request_coverage - view_teammates meta: total_count: 15 current_page: 1 total_pages: 2 per_page: 25 current_shift: user_timezone: America/New_York open_shifts: summary: Open shifts available for claiming value: items: - id: 456 name: Evening Shift date: Tuesday, Jan 28 start_time: '2025-01-28T14:00:00Z' end_time: '2025-01-28T22:00:00Z' location: id: 2 name: Mall Location status: open urgent: true needs_coverage: true available_actions: - claim - view_details meta: total_count: 5 type: open_shifts marketplace_available: summary: Marketplace - Available shifts to claim value: items: - id: 789 name: Weekend Shift date: Saturday, Feb 1 start_time: '2025-02-01T10:00:00Z' end_time: '2025-02-01T18:00:00Z' formatted_date: Saturday, Feb 01 formatted_time: 10:00 AM - 06:00 PM location: id: 3 name: North Branch status: scheduled urgent: false needs_coverage: true available_actions: - claim - view_details marketplace_info: has_listing: true listing_id: 456 price: 50.0 currency: USD listed_by: 123 listed_at: '2025-01-15T10:00:00Z' listed_by: id: 123 name: Grace Kulin job_title: Product Manager profile_photo_url: https://hub.workforce.mangoapps.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6NTk1LCJwdXIiOiJibG9iX2lkIn19--3c6dbf568dc4bf5029665ab667828e9ef1ddb58e/IMG_0130.jpg meta: total_count: 8 current_page: 1 total_pages: 1 per_page: 25 type: marketplace_available marketplace_claimed: summary: Marketplace - Shifts I've claimed value: items: - id: 890 name: Evening Shift date: Thursday, Jan 30 start_time: '2025-01-30T15:00:00Z' end_time: '2025-01-30T23:00:00Z' formatted_date: Thursday, Jan 30 formatted_time: 03:00 PM - 11:00 PM location: id: 4 name: South Branch status: scheduled urgent: false needs_coverage: false available_actions: - view_details - request_coverage marketplace_info: has_listing: true listing_id: 457 price: 45.0 currency: USD listed_by: 456 listed_at: '2025-01-20T14:00:00Z' listed_by: id: 456 name: John Smith job_title: Shift Supervisor profile_photo_url: https://hub.workforce.mangoapps.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6NTk1LCJwdXIiOiJibG9iX2lkIn19--3c6dbf568dc4bf5029665ab667828e9ef1ddb58e/profile.jpg picked_by: id: 1256 name: Grace Kulin job_title: Product Manager profile_photo_url: https://hub.workforce.mangoapps.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6NTk1LCJwdXIiOiJibG9iX2lkIn19--3c6dbf568dc4bf5029665ab667828e9ef1ddb58e/IMG_0130.jpg meta: total_count: 3 current_page: 1 total_pages: 1 per_page: 25 type: marketplace_claimed marketplace_listed: summary: Marketplace - Shifts I've listed value: items: - id: 901 name: Late Night Shift date: Friday, Feb 7 start_time: '2025-02-07T22:00:00Z' end_time: '2025-02-08T06:00:00Z' formatted_date: Friday, Feb 07 formatted_time: 10:00 PM - 06:00 AM location: id: 1 name: Downtown Store status: scheduled urgent: false needs_coverage: true available_actions: - view_details marketplace_info: has_listing: true listing_id: 458 price: 75.0 currency: USD listed_by: 789 listed_at: '2025-01-25T09:00:00Z' listed_by: id: 789 name: Sarah Johnson job_title: Operations Manager profile_photo_url: https://hub.workforce.mangoapps.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6NTk1LCJwdXIiOiJibG9iX2lkIn19--3c6dbf568dc4bf5029665ab667828e9ef1ddb58e/sarah.jpg meta: total_count: 2 current_page: 1 total_pages: 1 per_page: 25 type: marketplace_listed '304': "$ref": "#/components/responses/NotModified" '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/Error" post: tags: - Shifts summary: Create a shift description: | Creates one shift at the organization's default location, and optionally assigns people to it. Requires the `write:shifts` scope, a manager-or-above role and the Shifts **Create** permission (a manager limited to some sites may create only where they manage). - The shift fields are wrapped in `shift`. `location_id` is NOT accepted here: sending it answers 400 `location_id_not_settable`. To create a shift at a specific location use `POST /shifts/bulk_create` (one row is fine). - `user_ids` (top level, beside `shift`) assigns people; each must belong to this organization. Assignees are notified after the shift is saved. - Coverage (`needs_coverage`) is computed from the roster after the save; it cannot be sent. requestBody: required: true content: application/json: schema: type: object required: - shift properties: shift: type: object description: | The shift's fields. On create, `name`, `start_time` and `end_time` are required. `location_id` is refused on create (400) and ignored on update; `needs_coverage` is computed, never sent. An explicit `"urgent": null` is ignored (the flag is left as it was). properties: name: type: string description: type: string nullable: true start_time: type: string format: date-time end_time: type: string format: date-time status: type: string description: Defaults to the shift's initial status when omitted location_department_id: type: integer nullable: true description: A department of the shift's location required_staff_count: type: integer urgent: type: boolean shift_label_id: type: integer nullable: true notes: type: string nullable: true planned_breaks_attributes: type: array items: type: object properties: id: type: integer description: An existing planned break to change (omit to add one) break_type_id: type: integer timing_type: type: string scheduled_time: type: string window_start: type: string window_end: type: string timing_preferences: type: object is_required: type: boolean _destroy: type: boolean user_ids: type: array items: type: integer description: | People to assign (members of this organization). Omit to leave the roster alone; on update, an empty array clears it. example: shift: name: Morning Shift start_time: '2026-10-05T08:00:00Z' end_time: '2026-10-05T16:00:00Z' required_staff_count: 3 notes: Truck delivery at 9 user_ids: - 101 - 102 responses: '201': description: Shift created content: application/json: schema: type: object required: - id - name - start_time - end_time - status - created_at - updated_at properties: id: type: integer name: type: string description: type: string nullable: true notes: type: string nullable: true start_time: type: string format: date-time end_time: type: string format: date-time status: type: string location_id: type: integer nullable: true location_department_id: type: integer nullable: true schedule_id: type: integer nullable: true scheduling_group_id: type: integer nullable: true scheduling_sub_group_id: type: integer nullable: true shift_type: type: string nullable: true required_staff_count: type: integer nullable: true needs_coverage: type: boolean urgent: type: boolean ends_next_day: type: boolean nullable: true is_open_shift: type: boolean nullable: true is_ad_hoc: type: boolean nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time location: type: object nullable: true properties: id: type: integer name: type: string users: type: array items: type: object properties: id: type: integer first_name: type: string last_name: type: string name: type: string job_title: type: string nullable: true planned_breaks: type: array items: type: object properties: id: type: integer break_type_id: type: integer timing_type: type: string scheduled_time: type: string nullable: true window_start: type: string nullable: true window_end: type: string nullable: true duration_minutes: type: integer nullable: true is_required: type: boolean '400': description: | `location_id_not_settable` (location_id was sent — use `POST /shifts/bulk_create`), or the `shift` object is missing. content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Machine readable error code message: type: string description: Human readable error message details: type: object description: Additional error context required: - error example: error: code: location_id_not_settable message: location_id cannot be set on this endpoint. Use POST /api/v1/shifts/bulk_create to create a shift at a specific location. details: param: shift[location_id] '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/Error" '403': description: | Refused. `error.code` says which gate refused it, and `error.message` why: * `insufficient_permissions` — the token lacks `write:shifts` (`{"error": {"code": "insufficient_permissions", "message": "Required scope: write:shifts"}}`); * `forbidden` — the person's role, site or Shifts permission refused it: `{"error": {"code": "forbidden", "message": "You don't have permission to manage shifts"}}` (not a manager), `{"error": {"code": "forbidden", "message": "You do not have permission to manage shifts at this location"}}` (another site), `{"error": {"code": "forbidden", "message": "Not authorized to access this shift"}}` (a shift they may not see; update and delete only), or `{"error": {"code": "forbidden", "message": "You don't have permission to shifts."}, "status": "error", "success": false, "message": "…"}` (the Shifts Create / Edit / Delete permission). content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string message: type: string status: type: string success: type: boolean '422': description: Validation error content: application/json: schema: "$ref": "#/components/schemas/ValidationErrors" "/shifts/bulk_create": post: tags: - Shifts summary: Create several shifts description: | Creates each row as its own shift; a failed row does not stop the others. Unlike `POST /shifts`, a row may name its `location_id`. Rows carry no roster: every shift is created unstaffed, so no one is notified. A row with a `schedule_id` in a published schedule is published at once. Requires `write:shifts`, a manager-or-above role and the Shifts **Create** permission. requestBody: required: true content: application/json: schema: type: object required: - shifts properties: shifts: type: array items: type: object description: One row of POST /shifts/bulk_create or PUT /shifts/bulk_update (unwrapped — no `shift` key). properties: name: type: string description: type: string nullable: true start_time: type: string format: date-time end_time: type: string format: date-time status: type: string location_id: type: integer location_department_id: type: integer nullable: true schedule_id: type: integer nullable: true required_staff_count: type: integer urgent: type: boolean ends_next_day: type: boolean is_open_shift: type: boolean notes: type: string nullable: true example: shifts: - name: Morning Shift location_id: 12 start_time: '2026-10-05T08:00:00Z' end_time: '2026-10-05T16:00:00Z' required_staff_count: 3 responses: '200': description: Every row was created content: application/json: schema: type: object properties: message: type: string example: All shifts created successfully '400': description: "`invalid_shifts_payload` — `shifts` is not an array of shift objects" content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Machine readable error code message: type: string description: Human readable error message details: type: object description: Additional error context required: - error '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/Error" '403': description: Forbidden content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: Some rows failed. The rows in `results.success` WERE created. content: application/json: schema: type: object properties: message: type: string example: Some shifts failed to create results: type: object properties: success: type: array description: IDs of the shifts that were written items: type: integer failed: type: array items: type: object properties: id: type: integer description: bulk_update only params: type: object description: bulk_create only — the row as received errors: type: array items: type: string code: type: string description: "`externally_managed` when the shift is managed in the workforce management system" "/shifts/bulk_update": put: tags: - Shifts summary: Update several shifts description: | Updates each row (matched by `id` in this organization); a failed row does not stop the others. A row that moves a shift to another `schedule_id` takes that schedule's published state. A shift managed in the workforce management system (e.g. UKG) is refused per row with `code: externally_managed`. With the organization's "edit past shifts" setting off, a request that touches a shift that has already ended in a published schedule is refused whole (422 `past_shift_locked`). People assigned to a materially changed shift are notified once each. Requires `write:shifts`, a manager-or-above role and the Shifts **Edit** permission. A row that cancels a shift (`status` set to `cancelled`) makes the call delete-level (owner decision 2026-10-04, #6721): requires the `destructive:scheduling` scope. requestBody: required: true content: application/json: schema: type: object required: - shifts properties: shifts: type: array items: allOf: - type: object required: - id properties: id: type: integer - type: object description: One row of POST /shifts/bulk_create or PUT /shifts/bulk_update (unwrapped — no `shift` key). properties: name: type: string description: type: string nullable: true start_time: type: string format: date-time end_time: type: string format: date-time status: type: string location_id: type: integer location_department_id: type: integer nullable: true schedule_id: type: integer nullable: true required_staff_count: type: integer urgent: type: boolean ends_next_day: type: boolean is_open_shift: type: boolean notes: type: string nullable: true example: shifts: - id: 3901 start_time: '2026-10-05T09:00:00Z' end_time: '2026-10-05T17:00:00Z' responses: '200': description: Every row was updated content: application/json: schema: type: object properties: message: type: string example: All shifts updated successfully '400': description: "`invalid_shifts_payload` — `shifts` is not an array of shift objects" content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Machine readable error code message: type: string description: Human readable error message details: type: object description: Additional error context required: - error '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/Error" '403': description: Forbidden content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: | Some rows failed (the rows in `results.success` WERE updated), or `past_shift_locked` (nothing was changed; `details.shift_ids` names the locked shifts). content: application/json: schema: oneOf: - type: object properties: message: type: string example: Some shifts failed to create results: type: object properties: success: type: array description: IDs of the shifts that were written items: type: integer failed: type: array items: type: object properties: id: type: integer description: bulk_update only params: type: object description: bulk_create only — the row as received errors: type: array items: type: string code: type: string description: "`externally_managed` when the shift is managed in the workforce management system" - type: object properties: error: type: object properties: code: type: string description: Machine readable error code message: type: string description: Human readable error message details: type: object description: Additional error context required: - error "/shifts/{id}": get: tags: - Shifts summary: Get shift details description: | Retrieves detailed information about a specific shift, including: - Basic shift information (name, times, location, status) - Detailed location information - Shift details (description, notes, staffing counts) - **Marketplace listing information** (when available) - `listing_type`: Type of listing (pickup, trade_only, both) - `listing_status`: Current status (open, filled, closed, cancelled) - Price, currency, and listing metadata - Available actions for the current user - Assignment capabilities parameters: - name: id in: path required: true description: Shift ID schema: type: integer example: 3901 - name: format in: query required: false description: Response format type schema: type: string enum: - minimal - standard - detailed default: detailed - name: include in: query required: false description: Additional fields to include (comma-separated) schema: type: string example: teammates,notes,attendance responses: '200': description: Shift details retrieved successfully content: application/json: schema: allOf: - type: object properties: id: type: integer example: 123 managed_by: type: string nullable: true example: UKG description: 'The workforce management system of record that owns this shift ("Managed in UKG"), or null. A managed shift is read-only here: coverage requests and edits answer 422 `externally_managed`.' name: type: string example: Morning Shift description: type: string nullable: true start_time: type: string format: date-time example: '2025-01-27T09:00:00Z' end_time: type: string format: date-time example: '2025-01-27T17:00:00Z' formatted_date: type: string description: Human-readable date format example: Monday, Jan 27 formatted_time: type: string description: Human-readable time range example: 9:00 AM - 5:00 PM status: type: string enum: - scheduled - completed - cancelled - open example: scheduled urgent: type: boolean description: Whether this shift is marked as urgent example: false needs_coverage: type: boolean description: Whether this shift needs coverage example: false can_list_for_coverage: type: boolean description: Whether the current user can list this shift for coverage in the marketplace example: true is_already_listed: type: boolean description: Whether this shift is already listed in the marketplace by the current user example: false required_users: type: integer description: Number of users required for this shift location: type: object properties: id: type: integer example: 1 name: type: string example: Downtown Store address: type: string nullable: true phone: type: string nullable: true users: type: array items: "$ref": "#/components/schemas/User" available_actions: type: array description: Actions available to the current user for this shift items: type: string enum: - view_details - request_coverage - report_lateness - view_teammates - claim example: - view_details - request_coverage - view_teammates teammates: type: array description: Other users assigned to this shift (when include=teammates) nullable: true items: type: object properties: id: type: integer description: User ID name: type: string description: User full name job_title: type: string nullable: true description: User's job title/role profile_photo_url: type: string nullable: true description: Full-size profile photo URL (200x200) or avatar placeholder profile_photo_thumbnail_url: type: string nullable: true description: Thumbnail profile photo URL (40x40) optimized for list views listed_by: type: object nullable: true description: User who listed this shift in the marketplace (teammate format, present for marketplace shifts) properties: id: type: integer description: User ID name: type: string description: User full name job_title: type: string nullable: true description: User's job title/role profile_photo_url: type: string nullable: true description: Full-size profile photo URL (200x200) or avatar placeholder profile_photo_thumbnail_url: type: string nullable: true description: Thumbnail profile photo URL (40x40) optimized for list views picked_by: type: object nullable: true description: User who claimed/picked up this shift from the marketplace (teammate format, present when shift was claimed) properties: id: type: integer description: User ID name: type: string description: User full name job_title: type: string nullable: true description: User's job title/role profile_photo_url: type: string nullable: true description: Full-size profile photo URL (200x200) or avatar placeholder profile_photo_thumbnail_url: type: string nullable: true description: Thumbnail profile photo URL (40x40) optimized for list views marketplace_info: type: object nullable: true description: Marketplace listing information (present when shift has marketplace listing) properties: has_listing: type: boolean description: Whether this shift has an active marketplace listing example: true listing_id: type: integer description: ID of the marketplace listing example: 880 listing_status: type: string enum: - open - filled - closed - cancelled description: Current status of the marketplace listing example: open lister_status: type: string enum: - open - filled - traded - closed - cancelled description: 'Present only when the listing is the caller''s own. The status as its lister reads it: listing_status, except a listing filled by an accepted trade is traded (filled = picked up). Switch on this key, never on lister_status_label.' example: traded lister_status_label: type: string description: Present only when the listing is the caller's own. The word the web and phone pages show the lister (Available, Covered, Traded, Closed, Cancelled), in the language the client asks for (the locale param, else Accept-Language, else the person's own language). example: Traded listing_type: type: string enum: - pickup - trade_only - both description: Type of marketplace listing - pickup (direct claim), trade_only (requires application/trade), or both (accepts either) example: pickup price: type: number format: float description: Price offered for the shift example: 0.01 currency: type: string description: Currency code (e.g., USD) example: USD listed_by: type: integer description: User ID of the person who listed the shift (legacy field, use listed_by object instead) example: 1487 listed_at: type: string format: date-time description: When the shift was listed in the marketplace example: '2025-12-01T10:05:00Z' notes: type: string nullable: true description: Shift notes (when include=notes) created_at: type: string format: date-time updated_at: type: string format: date-time - type: object properties: can_list_for_coverage: type: boolean description: Whether the current user can list this shift for coverage example: true is_already_listed: type: boolean description: Whether this shift is already listed by the current user example: false placements: type: array maxItems: 1 description: | Communications messages booked into THIS shift for the caller (audience, dismissal and acknowledgement already applied) — at most one today; an array so the shape can grow. Rendering it counts as "shown", as on the web. items: "$ref": "#/components/schemas/CommsPlacement" examples: shift_with_marketplace_listing: summary: Shift with marketplace listing value: id: 3901 name: Full Day Coverage - Pune Office start_time: '2025-12-06T04:30:00Z' end_time: '2025-12-06T13:00:00Z' formatted_date: Friday, Dec 06 formatted_time: 04:30 AM - 01:00 PM location: id: 42 name: Pune Office status: scheduled urgent: false needs_coverage: false available_actions: - view_details - request_coverage marketplace_info: has_listing: true listing_id: 880 listing_status: open listing_type: pickup price: '0.01' currency: USD listed_by: 1487 listed_at: '2025-12-01T10:05:00Z' listed_by: id: 1487 name: John Doe job_title: Operations Manager profile_photo_url: https://hub.workforce.mangoapps.com/avatar/1487 location_details: id: 42 name: Pune Office address: 123 Tech Park, Pune phone: "+91-20-12345678" shift_details: description: Regular operations shift notes: Remember to bring your access card required_staff_count: 5 current_staff_count: 4 can_list_for_coverage: false is_already_listed: true shift_without_marketplace: summary: Shift without marketplace listing value: id: 767 name: Operations - Early Shift start_time: '2025-09-23T14:00:00Z' end_time: '2025-09-23T22:30:00Z' formatted_date: Tuesday, Sep 23 formatted_time: 02:00 PM - 10:30 PM location: id: 265 name: Issaquah Office status: scheduled urgent: false needs_coverage: false available_actions: - view_details location_details: id: 265 name: Issaquah Office address: 1495 11th Avenue Northwest phone: '' shift_details: description: '' notes: required_staff_count: 4 current_staff_count: 4 can_list_for_coverage: false is_already_listed: false '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/Error" '403': description: Not authorized to access this shift (`error.code` is `forbidden`). content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string example: error: code: forbidden message: Not authorized to access this shift '404': description: Shift not found content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Machine readable error code message: type: string description: Human readable error message details: type: object description: Additional error context required: - error example: error: code: shift_not_found message: Shift not found patch: tags: - Shifts summary: Update a shift description: | Updates the shift's own fields (wrapped in `shift`) and, when `user_ids` is sent, replaces its roster (`user_ids: []` clears it). `location_id` is not permitted here and is ignored. People assigned to the shift are told about a material change (time, place, cancellation) after it is saved. Requires `write:shifts`, a manager-or-above role, the Shifts **Edit** permission, and access to this shift's site. Refused with 422 when the shift is managed in the workforce management system (`externally_managed`), or has already ended in a published schedule while the organization's "edit past shifts" setting is off (`past_shift_locked`). A roster that takes off someone working the shift is delete-level (owner decision 2026-10-04): that request also requires `destructive:scheduling`. Adding people, or dropping someone who declined, needs only `write:shifts`. Cancelling a shift (`shift.status` set to `cancelled`) is delete-level (owner decision 2026-10-04, #6721): requires the `destructive:scheduling` scope. parameters: - name: id in: path required: true description: Shift ID schema: type: integer requestBody: required: true content: application/json: schema: type: object required: - shift properties: shift: type: object description: | The shift's fields. On create, `name`, `start_time` and `end_time` are required. `location_id` is refused on create (400) and ignored on update; `needs_coverage` is computed, never sent. An explicit `"urgent": null` is ignored (the flag is left as it was). properties: name: type: string description: type: string nullable: true start_time: type: string format: date-time end_time: type: string format: date-time status: type: string description: Defaults to the shift's initial status when omitted location_department_id: type: integer nullable: true description: A department of the shift's location required_staff_count: type: integer urgent: type: boolean shift_label_id: type: integer nullable: true notes: type: string nullable: true planned_breaks_attributes: type: array items: type: object properties: id: type: integer description: An existing planned break to change (omit to add one) break_type_id: type: integer timing_type: type: string scheduled_time: type: string window_start: type: string window_end: type: string timing_preferences: type: object is_required: type: boolean _destroy: type: boolean user_ids: type: array items: type: integer description: | People to assign (members of this organization). Omit to leave the roster alone; on update, an empty array clears it. example: shift: end_time: '2026-10-05T17:00:00Z' required_staff_count: 4 responses: '200': description: Shift updated content: application/json: schema: type: object required: - id - name - start_time - end_time - status - created_at - updated_at properties: id: type: integer name: type: string description: type: string nullable: true notes: type: string nullable: true start_time: type: string format: date-time end_time: type: string format: date-time status: type: string location_id: type: integer nullable: true location_department_id: type: integer nullable: true schedule_id: type: integer nullable: true scheduling_group_id: type: integer nullable: true scheduling_sub_group_id: type: integer nullable: true shift_type: type: string nullable: true required_staff_count: type: integer nullable: true needs_coverage: type: boolean urgent: type: boolean ends_next_day: type: boolean nullable: true is_open_shift: type: boolean nullable: true is_ad_hoc: type: boolean nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time location: type: object nullable: true properties: id: type: integer name: type: string users: type: array items: type: object properties: id: type: integer first_name: type: string last_name: type: string name: type: string job_title: type: string nullable: true planned_breaks: type: array items: type: object properties: id: type: integer break_type_id: type: integer timing_type: type: string scheduled_time: type: string nullable: true window_start: type: string nullable: true window_end: type: string nullable: true duration_minutes: type: integer nullable: true is_required: type: boolean '400': description: The `shift` object is missing content: application/json: schema: type: object properties: error: type: object properties: code: type: string description: Machine readable error code message: type: string description: Human readable error message details: type: object description: Additional error context required: - error '401': description: Unauthorized content: application/json: schema: "$ref": "#/components/schemas/Error" '403': description: | Refused. `error.code` says which gate refused it, and `error.message` why: * `insufficient_permissions` — the token lacks `write:shifts` (`{"error": {"code": "insufficient_permissions", "message": "Required scope: write:shifts"}}`); * `forbidden` — the person's role, site or Shifts permission refused it: `{"error": {"code": "forbidden", "message": "You don't have permission to manage shifts"}}` (not a manager), `{"error": {"code": "forbidden", "message": "You do not have permission to manage shifts at this location"}}` (another site), `{"error": {"code": "forbidden", "message": "Not authorized to access this shift"}}` (a shift they may not see; update and delete only), or `{"error": {"code": "forbidden", "message": "You don't have permission to shifts."}, "status": "error", "success": false, "message": "…"}` (the Shifts Create / Edit / Delete permission). content: application/json: schema: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string message: type: string status: type: string success: type: boolean '404': description: Not found content: application/json: schema: "$ref": "#/components/schemas/Error" '422': description: | Validation failed (`errors[]`, one entry per attribute), or `externally_managed` / `past_shift_locked` (an `error` object). content: application/json: schema: oneOf: - type: object properties: errors: type: array items: type: object properties: field: type: string description: Field name with validation error message: type: string description: Validation error message code: type: string description: Always `validation_error` field_name: type: string description: | Present only when an error on `base` is about one named field — a survey or form question left blank (`"